Receive Events and Respond

2 minute read

After you have set up the necessary webhooks, it is time to start receiving events and responding to them.

Receive an Event

Every time an event you subscribed to happens, we issue a POST request to the URL specified in the webhook. The request body contains the event data in JSON format and the event name. The request Sign-Data header includes a special signature that can help you verify that the event is coming from us.

Example event structure:

Sign-Type: HMACSHA256
Sign-Data: NmU8bbuG/FT/fOQqUBXTMcZgQj1EZ4SIaC1Lmg8XuNg=
Content-Type: application/json; charset=utf-8
Content-Length: 576

{
   "Object": {...},
   "EventType": "..."
}
Header Description
Sign-Type The payload encoding method.
Sign-Data The payload signature that is a base-64 encoded UTF-8 string.
Use this signature to check the event authenticity.
Parameter Description
Object An event object that contains new or updated data. Each event is different, therefore the structure of the event object depends on the object type. See Event Objects for examples.
EventType The type of the event that has happened.

Respond to a Webhook

Each time you receive our events, respond with a 2xx status code within five seconds. That is how we know that your server has received data from ServiceChannel. Any other code means that you have not got our notification.

Respond to a Webhook

Failed Requests

When you do not respond within five seconds or we receive an invalid status code, we will try re-sending an event three times with a 5-minute delay. After that we will delete the event data.

When a subscription accumulates 1000 consecutive failed requests, we will temporarily disable the webhook it belongs to. After 12 hours we will enable this webhook back, but if any subscription within this webhook receives 1000 consecutive fails, we will permanently disable this webhook. You can reactivate it either via the API or UI, but first check your server and the target URL.

Verify an Event

ServiceChannel signs all webhook events by including a signature in each event Sign-Data header. This signature allows you to validate that events are sent by SC, not by a third party.

We recommend verifying webhook signatures to confirm the request origin and integrity.

Step 1. Obtain your signing key

A signing key is used to generate event signatures. It is unique for each subscriber and provider and will always be same unless you regenerate it for some reason.

Send the following GET request to obtain your signing key.

GET /NotificationSubscriptions/SigningKey

Example request:

GET https://sb2api.servicechannel.com/v3/NotificationSubscriptions/SigningKey HTTP/1.1
Authorization: Bearer {access_token}

Example response:

{
   "Key": "8ba540c8a1148be16f3a69378cd30a5186dd56aec4da7880b6a101a47b3219d7543fc105dc6d7dd258163сс0bac9f2f2cd866200c5344f13506b8b89275236d3"
}

Response code: HTTP/1.1 200 OK

The response contains your signing key.

Note: You can also view and copy your signing key in the UI. See Get the Signing Key.

Step 2. Get the expected signature

Compute an HMAC using the SHA256 algorithm. Use the event body as a message and your signing key as a secret key.

  • Input: event body
  • Input type: text
  • Key: your signing key
  • Key type: text
  • SHA variant: SHA256
  • Output type: Base-64

Step 3. Compare signatures

Compare the signature in the Sign-Data header to the expected signature. If the signatures match, the request is from ServiceChannel.