Webhooks for Transactional SMS with OAuth 2.0

You can secure your SMS callback webhooks with OAuth 2.0 authentication. Instead of accepting webhook requests without verification or relying on a long-lived static secret, Insider One requests a short-lived access token from your authorization server before sending each callback and includes it in the Authorization: Bearer <token> header. Your endpoint can validate this token before processing the webhook payload, ensuring that callback requests originate from Insider One.

Using OAuth 2.0 to authenticate webhook requests provides the following benefits:

• Verify that webhook requests originate from Insider One and reject unauthorized requests.

• Use short-lived access tokens instead of managing a long-lived shared secret.

• Protect SMS event data with a standards-based authentication mechanism.

• Help meet enterprise security and compliance requirements without changing your webhook payload format.

Set up webhook

You can set up the callback within the body payload to receive webhook events for your transactional SMS by adding the following sample object at the end of the payload:

{
    "callback": "https://yourdomain/9c99bc26-373e-4847-b725-d7103803c111"
}

Callback event types

Sample delivered event:

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "event": "delivered",
  "phoneNumber": "+905551234567",
  "partCount": 1,
  "uniqueArgs": { "orderId": "12345" },
  "timestamp": 1234567890
}

Sample undelivered event:

{
  "id": "sms-a1234567-b123-c123-d123-e123f123456",
  "event": "undelivered",
  "phoneNumber": "+905551234567",
  "reason": { "message": "Soft Bounce", "code": 1404 },
  "uniqueArgs": { "orderId": "12345" },
  "timestamp": 1234567890
}