Overview

Paymos sends an HTTPS POST when an invoice, a withdrawal, or a payment-channel deposit changes state. Webhooks are the authoritative asynchronous signal for your backend: API responses start an operation, while webhook events tell you what happened after blockchain processing.

Integration flow

1. Create a webhook endpoint in Dashboard → Developer → Webhooks.
2. Choose one or more event categories: Invoice, Withdrawal, Payment channel.
3. Optionally restrict invoice and payment-channel events to selected projects — one filter covers both. Withdrawal events are merchant-wide and ignore it.
4. Store the displayed whsec_… secret on your server.
5. Verify every delivery against the unchanged raw request body.
6. Persist event_id, acknowledge with 2xx, and process the event asynchronously.

Production and Sandbox have separate endpoints, secrets, and events. A sandbox event is never delivered to a production endpoint.

Endpoint rules

• The URL must use HTTPS.
• The URL may name port 443 — what a URL without a port uses — or any port from 1024 up. Other ports are refused when you save, and an endpoint that already has one gets no deliveries.
• Up to 10 endpoints can be configured per merchant and environment.
• The same active URL cannot be registered twice in one environment.
• An endpoint must subscribe to at least one category.
• No project filter means every project is included.
• Suspending or deleting an endpoint stops new deliveries to it.

Delivery headers

Header	Contract
Content-Type	application/json; charset=utf-8
X-Webhook-Id	Same evt_… value as event_id in the body; not covered by the signature
X-Webhook-Timestamp	Unix seconds for this delivery attempt
X-Webhook-Signature	t={timestamp},v1={hmac_hex}; may contain two v1 values during rotation

Delivery is at-least-once and ordering is not guaranteed. Deduplicate on event_id from the verified body, then apply the resource state from data instead of counting events or assuming arrival order.

X-Webhook-Id is there for your logs, not for deduplication. The signature covers only the timestamp and the body, so a captured delivery can be resent with a different X-Webhook-Id and still verify while its timestamp passes your check — and a handler keyed on the header processes that copy a second time.

Webhook documentation

• Event catalog — every invoice, withdrawal, and payment-channel event type
• Payload contract — envelope and resource snapshots
• Verify signatures — raw-body HMAC verification and secret rotation
• Delivery and retries — timeout, backoff, idempotency, and replay
• Test webhooks — sandbox prerequisites and the interactive playground