Skip to main content
A webhook (whk_*) is a URL you register so Natural can push events to your server as they happen, instead of you reading each resource for changes. When a payment completes, a deposit lands, or a customer connects, Natural sends the event to your URL. An event (evt_*) is the record of what happened; a webhook is where Natural delivers it. One event can reach several webhooks, and every delivery of it carries the same event ID. For the event object and its snapshot, read the Events overview; for every event type and payload, read the Event catalog. Read a webhook with GET /webhooks/{webhookId}: enabledEvents names the event types the webhook subscribes to. sources says whose events it receives: "own" for your party, "connected" for customers connected to you. Webhooks are managed with an API key or a user session; an agent key cannot manage them.

​
Lifecycle

A webhook is ENABLED from creation and delivers every matching event. It becomes DISABLED when you set that status with PATCH /webhooks/{webhookId}, or when it fails every attempt for five consecutive events. A disabled webhook receives nothing until you set it back to ENABLED. DELETE /webhooks/{webhookId} removes it.

​
Delivery and retries

Each delivery is an HTTPS POST whose JSON body is the event. Natural treats any 2xx response as success and gives up on a single request after 30 seconds. A delivery that fails (non-2xx, network error, or timeout) is retried up to 7 attempts in total, with delays of 5 seconds, 5 minutes, 30 minutes, 2 hours, 8 hours, and 12 hours plus up to 20% jitter, so the last attempt lands roughly a day after the first. Retries reuse the same webhook-id, and an event can arrive more than once or out of order. You can send a stored event again for 90 days with POST /webhooks/{webhookId}/events/{eventId}/redeliver.

​
Signing

Natural signs every delivery the way the Standard Webhooks spec describes. The signing secret (whsec_...) is returned once, when you create the webhook. Each request carries webhook-id, webhook-timestamp, and webhook-signature headers; the signature is an HMAC-SHA256 over the ID, the timestamp, and the raw body, keyed with the decoded secret. Rotating the secret with POST /webhooks/{webhookId}/rotate-secret keeps the previous secret valid for a grace period you choose, up to 24 hours, and deliveries in that window carry one signature per active secret. Verification code lives in Receive events.

​
Best practices

Acknowledge as soon as the signature verifies, then process the event asynchronously. Slow handlers risk the 30-second timeout and trigger retries.
Retries and redeliveries reuse the same webhook-id, so Natural may deliver an event more than once. Record processed IDs and skip duplicates.
Never commit the whsec_ secret to source control. Rotate it with POST /webhooks/{webhookId} /rotate-secret and set expiresInSeconds (0 to 86400) to the overlap your deployment needs.
Retries and independent delivery mean events can arrive out of order. Most resource snapshots carry a version field to order by. chargeback snapshots do not, so order those by the event’s createdAt or read the resource again.
To register a webhook, verify signatures, and handle retries, follow Receive events. The full endpoint list starts at POST /webhooks.