API Reference
Start typing to search…

Introduction

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. If a non 2xx status code is returned, the webhook will be retried - subject to retry policy.
  • Each webhook contains a key field that you can use to deduplicate webhooks, please note, the same event sent to multiple URLs will have a unique key for each URL
  • Webhooks will typically arrive within a few seconds of the event. You should never rely on this - as delivery timing is not guaranteed, if the user is waiting, you should poll our API every 2-3 seconds, until the event is complete.
  • Webhooks will be sent as fast as possible, you should have a solution for handling high volumes of simulataneous events if you run batches of payments
  • Webhooks may arrive out of order

Webhook Security

  • Webhooks do not contain any sensitive information, just object references. You must fetch them via the API using your API credentials.
  • Webhooks must be to a HTTPS target on port 443.
  • All webhooks will come 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

A webhook that returns HTTP 200 or HTTP 204 will be considered successful, any other status will be deemed a failure.

By default webhooks are not retried unless you activate a retry policy. You can activate a webhook retry policy using the following syntax. Each retry will typically happen after 1 minute.

  • |: sets the number of attempts, eg https://targetA/url|3 (attempt 3 times)
  • >: failover to a second URL, eg https://targetA/url>https://targetB/url (attempt targetA, then attempt targetB)
  • ,: send a webhook to multiple destinations eg https://targetA/url,https://targetB/url (sent to targetA AND targetB)

Examples:

  • https://targetA/url - send the webhook to targetA
  • https://targetA/url|2 - send the webhook to targetA, if a HTTP 200 result not returned, try again 1 minute later
  • https://targetA/url|120 - send the webhook to targetA every minute until successful for 2 hours
  • https://targetA/url>https://targetB/url - send the webhook to targetA, if fail send to targetB after 1 minute
  • https://targetA/url>https://targetB/url>https://targetC/url - send the webhook to targetA, then targetB, then targetC (etc)
  • https://targetA/url|60>https://targetB/url|5 - send the webhook to targetA every minute for an hour then failover to targetB for 5 minutes
  • https://targetA/url,https://targetB/url - send the webhook to targetA and targetB
  • https://targetA/url|60,https://targetB/url|60 - send the webhook to targetA for up to an hour and targetB for up to an hour

Note: Retries are DISABLED in the sandbox environment.