Webhooks

Receive real-time notifications when events occur on Senddy.

Status: not yet available. Outbound webhooks are still in development and the endpoints listed in Developer Settings are placeholders. This page documents the intended contract so you can design against it. For payment notifications today, poll the API or use client.onPaymentReceived().

Overview#

Webhooks allow your application to receive real-time HTTP notifications when events occur. Instead of polling the API, Senddy sends a POST request to your configured endpoint.

Setting up webhooks#

Go to your Developer Settings
Navigate to the Webhooks section
Enter your endpoint URL (must be HTTPS)
Select the events you want to receive
Save your configuration

Event types#

Event	Description
`payment.received`	A payment was received to your address
`payment.confirmed`	A payment has been confirmed on-chain
`deposit.completed`	A deposit has been shielded into the privacy pool
`withdrawal.completed`	A withdrawal has been processed
`bridge.completed`	A cross-chain bridge transfer has arrived

Webhook payload#

All webhooks are delivered as HTTP POST requests with a JSON body:

JSON

{
  "id": "evt_abc123",
  "type": "payment.received",
  "timestamp": "2025-01-15T12:00:00Z",
  "data": {
    "amount": "50000000",
    "currency": "USDC",
    "memo": "Order 123"
  }
}

Verifying webhooks#

Each webhook request includes a signature header for verification:

X-Senddy-Signature: sha256=...

Verify the signature using your webhook secret (available in Developer Settings) to ensure the request is authentic.

Retry policy#

If your endpoint returns a non-2xx status code, Senddy will retry delivery:

1st retry: 1 minute after failure
2nd retry: 5 minutes
3rd retry: 30 minutes
4th retry: 2 hours
5th retry: 24 hours

After 5 failed attempts, the webhook is marked as failed and no further retries are attempted.

Requirements#

Webhooks are available on the Growth plan ($49/mo) and above
Endpoint must accept HTTPS POST requests
Endpoint must respond within 10 seconds
Maximum payload size: 64 KB