Webhooks

Register HTTPS callbacks for payment and funding events. Delivery is signed, SSRF-safe, retried via an outbox, and verifiable with the secret returned on create.

Same flow in MCP: rill_webhooks

Auth

Owner Supabase JWT required. Send Idempotency-Key on create. Save the signing secret from the create response, it is required to verify X-Rill-Signature on every delivery.

Authorization: Bearer <owner JWT>

Featured endpoints

Register a webhook

POST /webhooks

Register a callback URL for events such as payment.succeeded and funding.paid. Localhost callbacks are allowed outside production. List registered endpoints with GET /webhooks.

Parameter	Type	Required	Description
`url`	string	yes	HTTPS callback URL
`events`	string[]	no	Optional event allowlist; omit to receive the default set

Request body

body

{
  "url": "https://example.com/hooks/rill",
  "events": ["payment.succeeded", "funding.paid"]
}

What to save

Save the webhook id and signing secret. Verify X-Rill-Signature (v1,<hmac>), X-Rill-Timestamp (300s tolerance), and X-Rill-Webhook-Id on every delivery.

Catalog events with GET /webhooks/events.
Test with POST /webhooks/:id/test; retry with …/deliveries/:deliveryId/retry.
MCP twin: rill_webhooks action=create|list|test|delete.

All endpoints

POST/webhooksRegister URL (Idempotency-Key)
GET/webhooksList endpoints
GET/webhooks/eventsEvent catalog
DELETE/webhooks/:idDelete endpoint
GET/webhooks/:id/deliveriesDelivery log
POST/webhooks/:id/testSend test event
POST/webhooks/:id/deliveries/:deliveryId/retryRetry delivery

Signing and events

Headers: X-Rill-Signature (v1,<hmac>), X-Rill-Timestamp (300s tolerance), X-Rill-Webhook-Id. Verify with the secret returned on create.
Events include payment.succeeded, payment.failed, transfer.received, funding.paid, withdrawal.paid, withdrawal.failed, vw.revoked, allowance.reset, seller.withdrawn, resource.updated.