Webhooks

Webhooks

The platform supports web hooks as a way to integrate with external systems. Primarily this is used to send notifications of events within the Call Manager platform.

Supported Events

We currently support the following notification events:
  1. Account Created
    1. No Additional Data
  2. Account Consent Provided
    1. No Additional Data
  3. Call Flow Modified (Created, Updated, Deleted)
    1. Additional Data Includes: CallFlowId, Name, Number
  4. User Modified (Supports assigned number edit or voice routing policy change)
    1. Additional Data Includes: User Microsoft ID, UPN, Number, Voice Routing Policy
  5. Resource Account Modified (Supports assigned number edit or voice routing policy change)
    1. Additional Data Includes: Resource Account Microsoft ID, UPN, Number, Voice Routing Policy
  6. Support Request Raised
    1. Additional Data Includes: Name, Email, Subject, Message, Base64 Browser Screenshot (optionally provided by User)

Payload Format

An example payload is shown below. Note that the events array may contain more than one event. We recommend you process each event in the array.


  1. {
  2.   "events": [
  3.     {
  4.       "event_guid": "e4f8294b-c285-4fb4-af47-7c2f9b64d500", // Unique for each event
  5.       "accountId": "8db6bc47414b4a16", // Customer account
  6.       "clientState":"optional-client-value", // Optional secret value provided at brand creation time
  7.       "eventType":"accountConsentSuccess", // or another event: accountCreation, accountFirstCallFlow, supportRequest etc
  8.       "microsoftTenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
  9.       "version": 1, // Future webhooks may use an updated format
  10.       "payloadData":
  11.       {
  12.          // Additional data per event type. Format is key/value pair of information, e.g. UPN, or supportMessage etc.
  13.       }
  14.     }
  15.   ]
  16. }

Implementation Guidance

Security

To ensure the authenticity of a webhook, a unique signature is generated with each event and sent in the X-Hook-Signature header. This signature is a hash of the request body and is created using a shared secret key that is provided to you when you set up the webhook.

To verify the webhook:

  1. Use the shared secret key to compute the HMAC-SHA256 hash of the webhook request body.

  2. Compare your computed hash with the signature provided in the X-Hook-Signature header.

  3. If the signatures match, you can be sure the webhook was sent from us and the payload has not been tampered with.


Retry Mechanism

If a webhook fails (a non-2xx response), the platform will retry the delivery using an exponential back-off with a randomized delay.

  • Attempt 1: After 1 minute

  • Attempt 2: After 5 minutes

  • Attempt 3: After 30 minutes

  • Final Attempt: After 1 hour

If all four attempts fail, the webhook will be disabled automatically. The event will not be delivered, and you will need to re-enable the webhook from your account settings.

Your webhook endpoint should respond with a 2xx status code as quickly as possible (ideally within a few seconds). Do not perform long-running tasks like database operations or API calls in the webhook handler. Instead, accept the payload and queue the work to be processed asynchronously in the background. Your endpoint should also be idempotent, meaning it can safely process the same event multiple times without side effects.

Management

Contact your account manager to get setup with Webhooks.