Overview

Overview

Webhook subscriptions allow Calypso to send HTTP notifications to a merchant endpoint when events happen with invoices, payouts, accounts, customers, and other supported objects.

Instead of repeatedly requesting object status from the API, subscribe to the required webhook events and update the merchant system when Calypso sends a notification.

How it works

1. Create a webhook subscription and pass the URL where the merchant system receives webhook requests.
2. Select either event groups through notificationServiceTypes, specific events through notificationEventTypes, or both.
3. When a subscribed event occurs, Calypso sends a POST request with event data to the configured URL.
4. Return HTTP 200 OK after the webhook is processed successfully.
5. If the merchant endpoint does not return 200 OK, Calypso retries delivery according to the retry policy.

Retry policy

If webhook delivery fails, Calypso retries delivery using a Fibonacci-like interval sequence.

Retry behavior	Description
First retry	30 seconds after the failed delivery attempt.
Next retries	60 s, 90 s, 150 s, 240 s, and so on.
Maximum retry interval	125,430 seconds, approximately 34 hours.
Total retry attempts	19 retries.
Success condition	The merchant endpoint returns HTTP 200 OK.

Subscription blocking

Calypso can block a webhook subscription if the merchant endpoint consistently returns errors.

Case	Description
Blocking condition	More than 100 failed webhook delivery attempts within 10 minutes and no successful delivery during that period.
How to unblock	Unblock the subscription in the Calypso UI.
After unblocking	Calypso automatically retries webhooks that failed during the blocked period.

unblocking-webhook-subscription.md

Related docs

Document	Link
Delivery order	Delivery order
Sign check	Sign check
Webhook payload	Webhook payload