> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Get notified when things happen on your account

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](/guides/concepts/events); for every event type and payload, read the [Event catalog](/api-reference/event-catalog).

Read a webhook with [`GET /webhooks/{webhookId}`](/api-reference/webhooks/get-webhook):

<Snippet file="api-examples/webhooks.get.response.mdx" />

`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}`](/api-reference/webhooks/update-webhook), 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}`](/api-reference/webhooks/delete-webhook) 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`](/api-reference/events/redeliver-event).

## Signing

Natural signs every delivery the way the [Standard Webhooks](https://www.standardwebhooks.com) 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`](/api-reference/webhooks/rotate-webhook-signing-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](/guides/webhooks/receive-events).

## Best practices

<AccordionGroup>
  <Accordion title="Return 2xx fast">
    Acknowledge as soon as the signature verifies, then process the event asynchronously. Slow
    handlers risk the 30-second timeout and trigger retries.
  </Accordion>

  <Accordion title="Deduplicate on webhook-id">
    Retries and redeliveries reuse the same `webhook-id`, so Natural may deliver an event more than
    once. Record processed IDs and skip duplicates.
  </Accordion>

  <Accordion title="Store the signing secret in a secrets manager">
    Never commit the `whsec_` secret to source control. Rotate it with [`POST /webhooks/{webhookId}
          /rotate-secret`](/api-reference/webhooks/rotate-webhook-signing-secret) and set `expiresInSeconds`
    (0 to 86400) to the overlap your deployment needs.
  </Accordion>

  <Accordion title="Don't depend on event ordering">
    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.
  </Accordion>
</AccordionGroup>

To register a webhook, verify signatures, and handle retries, follow [Receive events](/guides/webhooks/receive-events). The full endpoint list starts at [`POST /webhooks`](/api-reference/webhooks/create-webhook).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.