Skip to navigation
Guides

Webhooks

Register endpoints, verify signatures, and handle events

Natural sends real-time event notifications to your registered webhook endpoints using Standard Webhooks. This lets you react to payments, transfers, and other events without polling the API.

Register an endpoint

Register a webhook endpoint via the dashboard or API:

curl -X POST https://api.natural.co/webhooks \
  -H "Authorization: Bearer $NATURAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "url": "https://your-app.com/webhooks/natural",
        "events": ["payment.completed", "payment.failed", "transfer.completed"]
      }
    }
  }'

Verify signatures

All webhook deliveries include a signature in the webhook-signature header. Verify it using the Standard Webhooks library:

from standardwebhooks import Webhook
wh = Webhook(signing_secret)
payload = wh.verify(request.body, request.headers)

Event types

EventDescription
payment.createdA payment was initiated
payment.completedA payment was successfully delivered
payment.failedA payment failed
payment.cancelledA payment was cancelled
transfer.completedA deposit or withdrawal completed
transfer.failedA deposit or withdrawal failed
payment_request.fulfilledA payment request was paid
payment_request.expiredA payment request expired

Best practices

  • Respond quickly — Return a 2xx status within 5 seconds. Process events asynchronously if needed.
  • Handle duplicates — Use the event ID for idempotency. Natural may retry delivery.
  • Verify signatures — Always validate the webhook-signature header before processing.