Webhooks

A callback is an HTTP POST request with a notification made by the Sinch SMS REST API to a URI of your choosing.

The REST API expects the receiving server to respond with a response code within the 2xx success range. For 5xx the callback will be retried. For 429 the callback will be retried and the throughput will be lowered. For other status codes in the 4xx range the callback will not be retried. The first initial retry will happen 5 seconds after the first try. The next attempt is after 10 seconds, then after 20 seconds, after 40 seconds, after 80 seconds, doubling on every attempt. The last retry will be at 81920 seconds (or 22 hours 45 minutes) after the initial failed attempt.

Note that, with these callbacks, the Sinch SMS REST API will make a request to the URI of your choosing. This means that Sinch will be authenticating against your system. By making a request to your account manager, SMS REST API callbacks may be configured with the following options:

• Basic authentication is the simplest form of authentication. It enables access to the SMS API via a username and password. Basic Auth can be utilised in a callback by provisioning the callback URL with the appropriate username and password. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username and password must be accepted by your system.
• OAuth 2.0 is a standard form of authentication that provides enhanced security when compared to Basic Authentication. It uses access tokens to reduce the risk of credentials being intercepted. OAuth 2.0 can be utilised in a callback by provisioning the callback URL with username, password, response, scope, and the URL to fetch OAuth access token. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username, password, response, scope, and access token URL must be accepted by your system.
• HMAC Hash-based message authentication code (HMAC) is a cryptographic authentication technique that uses a hash function and a secret key. HMAC can also be configured alongside Basic Auth and OAuth. HMAC authentication can be assigned to a specific URL or an entire Service Plan. In either case, reach out to your account manager to configure HMAC authentication.
• AWS SNS is a managed service that provides message delivery from publishers to subscribers by routing messages through SNS topics. Users can utilise AWS SNS in a callback by provisioning the callback URL with an Access Key ID, Secret Key and Region.

Additionally, the SMS REST API supports customized headers in callbacks. Reach out to your account manager to configure customized callback headers.Your account manager will be able to configure callbacks associated with your account so that they include the header and value pairs you provide.