Webhooks are notifications of events that occur in the Shuttle system.
Handling Webhooks
- Webhooks are sent to a HTTPS endpoint on your server
- Webhook body is a JSON object
- The endpoint must return a 2xx status code. Any other status is treated as a failure.
- Each webhook contains a
keyfield that you can use to deduplicate webhooks. The same event sent to multiple URLs will have a uniquekeyfor each URL. - Webhooks will typically arrive within a few seconds of the event. Delivery timing is not guaranteed — if the user is waiting on a result, poll the API every 2-3 seconds rather than relying on webhook timing.
- Webhooks may arrive out of order.
- If you run batches of payments, ensure your endpoint can handle high volumes of simultaneous events.
Webhook Security
- Webhooks do not contain any sensitive information, just object references. Fetch the full object via the API using your credentials.
- Webhooks must target a HTTPS endpoint on port 443.
- All webhooks originate from one of the following IP addresses:
- 52.51.86.26
- 54.229.12.118
- 54.76.31.104
- 34.252.246.134
Webhook Retry Policy
By default, webhooks are not retried. A response of HTTP 200 or HTTP 204 is considered successful; any other status is a failure.
To activate retries, configure a retry policy in the webhook target URL. When retries are configured, each attempt occurs approximately 1 minute after the previous failure.
Note: Retries are disabled in the sandbox environment.
Webhook Configuration
Webhook targets are stored as a URL string. The string supports a simple syntax for configuring retries, failover, and multiple destinations. See the webhook_target field on the instance or the attach webhook endpoint.
Operators
| Operator | Description |
|---|---|
|N | Retry up to N times, with approximately 1 minute between each attempt |
> | Failover: if the current URL fails, try the next |
, | Fan-out: deliver to multiple destinations simultaneously |
Examples
https://targetA/url: send to targetA, no retrieshttps://targetA/url|2: send to targetA, retry once on failurehttps://targetA/url|120: retry every minute for up to 2 hourshttps://targetA/url>https://targetB/url: send to targetA; on failure, try targetBhttps://targetA/url>https://targetB/url>https://targetC/url: targetA, then targetB, then targetChttps://targetA/url|60>https://targetB/url|5: retry targetA for up to 1 hour, then fail over to targetB for up to 5 minuteshttps://targetA/url,https://targetB/url: send to both targetA and targetBhttps://targetA/url|60,https://targetB/url|60: send to both, each with up to 1 hour of retries