Copy page

Guides

Webhook Events

Overview

Spoke supports webhooks as a mechanism for notifying your systems when an event occurs. Webhooks are useful for listening to asynchronous events occurring on the Spoke platform, such as changes to a call's state over time; a change to the contact associated with a call; or a call recording becoming available.

To get started, you will need to configure a webhook in the Spoke account portal. Alternatively, you can use the Webhook API to configure a webhook. During configuration you will be given the option to specify event types you wish to receive notifications for. You will also be required to provide a valid, publicly routable HTTPS URL that accepts POST requests with the application/json content type.

Every Spoke event sent to your webhook is wrapped in the following standard wrapper that provides important information about the event, such as its type, a timestamp of when it was created, and the event data itself.

Securing Your Webhooks

Once your application is configured to receive events, it will listen for any event sent to the endpoint. For security reasons, we strongly recommend that you ensure requests to your endpoint come from Spoke. The easiest method to validate that a request was sent via Spoke is to verify the signature, and timestamp sent in every request against the secret that was provided to you when you created your webhook.

Verifying the signature

A request is considered valid based on the following conditions:

• The x-spoke-timestamp header is a valid UNIX timestamp, and represents a time sent within the last 5 minutes (using millisecond precision). This header allows the consumer to validate when a request was sent, to avoid replay attacks.
• The x-spoke-signature header is formatted as sha256=<HMAC algorithm cipher text>, and it contains the correct hash based on the hexadecimal representation of the SHA256 HMAC algorithm with the signing secret applied to <x-spoke-timestamp header value>.<request body>. The calculated hash includes the timestamp to ensure that an attacker cannot modify the timestamp without also invalidating the message signature.

A request can be validated via the following:

Code
const isValidSpokeRequest = (requestBody: string, signingSecret: string, spokeTimestamp: number, spokeSignature: string): boolean => {

  // Determine if timestamp is valid
  const isValidTimestamp = (Date.now() - spokeTimestamp) <= 300000; // 5 x 60 x 1000
  if (!isValidTimestamp) {
    return false;
  }

  // Determine if the signature is valid
  const [algorithm, cipher] = spokeSignature.split("=");
  const body = `${spokeTimestamp}.${requestBody}`

  const h = crypto.createHmac(algorithm, signingSecret);
  h.update(body);
  return h.digest("hex") === cipher;
}

Delivery Attempts, Retries and Event Ordering

Delivery Attempts

Spoke will attempt to deliver events to your webhooks 10 times, over the course of 24 hours with an exponential back off. For an event to be considered successfully delivered, your endpoint will need to respond with a valid 2XX HTTP status code within 5 seconds of the HTTP request being received. In the Developers section of the Account Portal, you can view all attempts to deliver an event to your endpoint.

Retries

Spoke will retry delivering a webhook event if the request fails and your endpoint responds with any of the following status codes:

• Server-side errors: 5xx
• Throttling errors: 429
• Request timeout errors: 408

Failed delivery attempts that respond with any other status codes will not be retried. For example, responses with a 400 status code (Bad Request) will not be retried, as it signals that repeating the same request will fail with the same error.

Automatic Disabling of Webhooks

In order to manage system capacity across the platform, Spoke will automatically disable a webhook once more than consecutive 1000 events have failed to deliver. The Spoke Administrator who created the webhook will be notified via email that the webhook has been disabled.

Order of Events

Spoke does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of events in order, and should handle these accordingly.

Example Timelines of Events

Below are some examples of when the above events might occur during the lifetime of some calls.

Note: These are example timelines. While most of the events will fire in a similar order to the ones given below, this is not guaranteed. See Order of Events for more details on how event ordering might affect your webhook.

Example Timelines of Call and Availability Events

---

Example 1 - Basic Call Timeline with User Answered Call

---

Example 2 - Unanswered Call to Team

---

Example 3 - Contact Assignment and Recording Transcript

Example Timelines of Conversation Events

---

Example 1

---

Example 2