Receive events

Register a URL, verify every delivery Natural signs, and process each event exactly once even when it arrives more than once. For the delivery model, read the Webhooks overview.

Register a webhook

Register your URL and the event types it subscribes to with POST /webhooks; the signing secret comes back once, in this response only, so store it immediately. Webhooks are managed with an API key or a user session; an agent key cannot manage them.

import uuid
from naturalpay import Natural

# NATURAL_API_KEY=sk_ntl_prod_...
client = Natural()

webhook = client.webhooks.create(
    url="https://yourdomain.com/hooks/natural",
    enabled_events=["wallet.created", "party.updated"],
    sources=["own", "connected"],
    idempotency_key=str(uuid.uuid4()),
)
signing_secret = webhook.data.attributes.signing_secret  # shown once, store securely

import Natural from "@naturalpay/sdk";

// NATURAL_API_KEY=sk_ntl_prod_...
const client = new Natural();

const webhook = await client.webhooks.create({
  url: "https://yourdomain.com/hooks/natural",
  enabledEvents: ["wallet.created", "party.updated"],
  sources: ["own", "connected"],
  idempotencyKey: crypto.randomUUID(),
});
const signingSecret = webhook.data.attributes.signingSecret; // shown once, store securely

# NATURAL_API_KEY=sk_ntl_prod_...
natural webhooks create \
  --json '{"url": "https://yourdomain.com/hooks/natural", "enabledEvents": ["wallet.created", "party.updated"], "sources": ["own", "connected"]}' \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/webhooks \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "url": "https://yourdomain.com/hooks/natural",
        "description": "Production webhook",
        "enabledEvents": ["wallet.created", "party.updated"],
        "sources": ["own", "connected"],
        "tags": { "env": "prod" }
      }
    }
  }'

The response carries the webhook with its signingSecret: A new webhook is ENABLED; it becomes DISABLED when you set that status or when it fails five events in a row. url must be HTTPS and publicly reachable. enabledEvents needs at least one entry: any event type from the Event catalog, or the wildcard "*" (which must be the only entry). sources defaults to ["own"]; add "connected" to also receive events a customer connection authorizes. Omitting "connected" never opts a webhook into customer events, and the event type must still match enabledEvents. description (up to 100 characters) and tags are optional.

Verify a signature

Every delivery is a POST whose JSON body is the event, with type naming what happened and the resource snapshot at data.object, and three lowercase headers carry the signature:

Header	Description
`webhook-id`	The event ID (`evt_...`), stable across retries. Use for idempotency.
`webhook-timestamp`	Unix epoch seconds when the delivery was signed.
`webhook-signature`	One or more space-separated `v1,<base64>` signatures.

Verify before trusting a payload. Use the official standardwebhooks library (Python and Node); construct it with your whsec_ secret and pass the raw body plus headers. verify returns the parsed event, or raises on a bad signature:

# FastAPI
import os
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks
from standardwebhooks import Webhook

app = FastAPI()
wh = Webhook(os.environ["NATURAL_WEBHOOK_SECRET"])  # the whsec_... value

@app.post("/hooks/natural")
async def handle(request: Request, background_tasks: BackgroundTasks):
    body = await request.body()  # raw bytes, required for verification
    try:
        event = wh.verify(body, dict(request.headers))
    except Exception:
        raise HTTPException(status_code=401, detail="Invalid signature")
    # Hand off async work and return 2xx fast.
    background_tasks.add_task(process_event, event, request.headers["webhook-id"])
    return {"received": True}

// Express
import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.NATURAL_WEBHOOK_SECRET!); // the whsec_... value

// express.raw keeps the body as exact bytes for verification.
app.post("/hooks/natural", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers as Record<string, string>);
  } catch {
    return res.status(401).send("Invalid signature");
  }
  // Hand off async work and return 2xx fast.
  void processEvent(event, req.headers["webhook-id"]);
  res.json({ received: true });
});

Verify against the raw request body, the exact bytes Natural sent. Parsing and re-serializing the JSON first changes the bytes and breaks verification.

The library handles two details for you: it rejects deliveries whose webhook-timestamp is outside a tolerance window, and it accepts a delivery if any of the space-separated signatures verifies. That second rule is what lets a rotation with POST /webhooks/{webhookId}/rotate-secret overlap two valid secrets: during the grace period you set with expiresInSeconds (0 to 86400 seconds), each delivery carries one signature per active secret, newest first.

Verify manually, without the library

The signed content is the string {webhook-id}.{webhook-timestamp}.{body}. Strip the whsec_ prefix from the secret, base64-decode the remainder for the HMAC key, compute HMAC-SHA256, and base64-encode the result. Compare it against each space-separated v1,<sig> entry.

import base64, hashlib, hmac

def verify(body: bytes, headers: dict, signing_secret: str) -> bool:
    key = base64.b64decode(signing_secret.removeprefix("whsec_"))
    signed = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.{body.decode()}"
    expected = base64.b64encode(hmac.new(key, signed.encode(), hashlib.sha256).digest()).decode()
    for entry in headers["webhook-signature"].split(" "):
        version, _, sig = entry.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False

import { createHmac, timingSafeEqual } from "crypto";

function verify(body: string, headers: Record<string, string>, signingSecret: string): boolean {
  const key = Buffer.from(signingSecret.replace(/^whsec_/, ""), "base64");
  const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${body}`;
  const expected = Buffer.from(createHmac("sha256", key).update(signed).digest("base64"));
  return headers["webhook-signature"].split(" ").some((entry) => {
    const [version, sig] = entry.split(",");
    if (version !== "v1" || !sig) return false;
    const sigBuf = Buffer.from(sig);
    return sigBuf.length === expected.length && timingSafeEqual(sigBuf, expected);
  });
}

Handle retries and replay

Treat every delivery as a possible duplicate, keyed on the event ID, and send a stored event again with POST /webhooks/{webhookId}/events/{eventId}/redeliver when your handler missed it. Natural treats any 2xx response as success and gives up on a single request after 30 seconds. A failed delivery (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. Every retry reuses the same webhook-id, so record the event IDs you have processed and skip any you have already seen. A webhook that fails every attempt for five consecutive events becomes DISABLED; set it back to ENABLED with PATCH /webhooks/{webhookId} once your handler is healthy. A connected delivery is authorized against the customer connection immediately before each send; if that check is temporarily unavailable, the delivery is deferred and re-checked about every 5 minutes for up to 24 hours without consuming a retry attempt. The webhook-id header is the event ID. GET /events lists the same events on demand and GET /events/{eventId} reads one, which is how you fill a gap after an outage. For a connected customer, pass partyId and eventType: history covers connected events created since the connection began plus any events actually delivered to one of your webhooks, and after revocation only the delivered records remain.

redelivery = client.events.redeliver(
    "whk_019cd1798d8f8560c82adba1d2912643",
    "evt_019cd1798d9190112b89219ccb1aaa44",
    idempotency_key=str(uuid.uuid4()),
)
print(redelivery.data.attributes.status)

const redelivery = await client.events.redeliver({
  webhookId: "whk_019cd1798d8f8560c82adba1d2912643",
  eventId: "evt_019cd1798d9190112b89219ccb1aaa44",
  idempotencyKey: crypto.randomUUID(),
});
console.log(redelivery.data.attributes.status);

natural events redeliver \
  --webhook-id whk_019cd1798d8f8560c82adba1d2912643 \
  --event-id evt_019cd1798d9190112b89219ccb1aaa44 \
  --idempotency-key "$(uuidgen)"

curl -X POST https://api.natural.com/webhooks/whk_019cd1798d8f8560c82adba1d2912643/events/evt_019cd1798d9190112b89219ccb1aaa44/redeliver \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

The response carries the pending redelivery: A redelivery starts PENDING, moves to DELIVERING while the request is in flight, and ends DELIVERED or FAILED; it is UNKNOWN when no response was recorded and CANCELED when the authorization check before sending no longer passes. You can redeliver an event for 90 days after it was created, to a webhook that was one of its original destinations. The webhook must be ENABLED and must still accept the event’s source: removing "connected" from sources closes redelivery of its connected events (webhook_source_disabled). One manual redelivery per event and webhook runs at a time, and you can request up to 10 per webhook per minute; beyond that the call returns redelivery_rate_limited. A redelivery keeps the original payload and webhook-id but uses the webhook’s current URL and active signing secret with a fresh webhook-timestamp and signature, and it can overlap with automatic retries, so handle it as a duplicate. A manual failure does not count toward automatic disabling. For a delegated event, the delegation that authorized the original delivery must still be active and grant access to that event type. Revoking it permanently closes redelivery for that event and webhook; a new delegation does not reopen it. A delegated redelivery goes only to the webhook that received the original delivery, never to the customer’s webhooks. Connected copies carry the same payload as the owner’s copy, with no connection metadata added and no fields removed. Which events reach a webhook with "connected" in sources:

Event	Connected delivery while the customer connection is active
`compliance_case.updated`, `wallet.created`, `deposit.completed`	Yes, independent of an agent’s operational permissions.
`delegation.activated`, `delegation.revoked`, `agent_delegation.revoked`, `agent_delegation_invitation.accepted`	No connected copy. Natural emits each identity event directly to both parties.
Every other event type	Only while an active agent delegation grants the matching read permission.

Payment milestones can produce separate sender and recipient events. sourcePartyId identifies the party whose view the event represents, and the recipient view omits sender-only details. A webhook connected to both parties can receive both views with different event IDs, so deduplicate on the event ID, not the payment ID.

Overview

Common use cases

Products

Guides

Register a webhook

Verify a signature

Handle retries and replay

​Register a webhook

​Verify a signature

​Handle retries and replay

Register a webhook

Verify a signature

Handle retries and replay