Outbound Webhooks

Outbound Webhooks can be used to forward the following events or messages to your applications or systems:

• Status receipts for the outbound messages sent using Webex Connect (E.g., Submitted, Failed, Delivered, etc. receipts are subject to channel-specific capabilities.)
• Incoming calls and messages from customers across channels and Incoming call events.

❗️

URL Endpoint Notifications

• We only support HTTPs URLs. We make a test call to the configured URL and expect a standard 200 HTTP Response before you can save your configuration. All notifications will be delivered by making POST requests.
• In case Webex Connect is not able to send a notification because of an unreachable URL, it will retry sending notifications three times each, after 60 seconds. The maximum request timeout for each notification is 10 seconds. The HTTP Responses for which retries are not performed are - 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308, 400, 402, 404, 405, 406, 407, 408, 409, 410, 411, 414, 415, 416, 418, 505.

📘

SHA256 and SHA512 support

With the v5.6.0 release (Oct 23), we have added support for SHA256 and SHA512 signatures while setting up outbound webhooks. The SHA1 signature option is no longer supported and isn’t allowed for new outbound webhook configurations. This does not impact existing functional outbound webhook configurations ( i.e. webhooks configured before the April 22 release).

Configuring Outbound Webhooks at a Service Level

To configure an outbound webhook for a given service on Webex Connect platform, perform the following steps:

1. Navigate to Assets > Integrations.

2. Click Add Integration > Outbound Webhook.

3. Enter/select details like Name, Entity, Endpoint Configuration.
   • Name - the name that you want to use for your outbound webhook configuration
   • Entity - the Service to which you want to associate your outbound webhook
   • URL - the URL at which the Webex Connect platform notifies your application of incoming events and messages.
4. Which Notifications Do You Want To Receive - select the required notification you want to receive for the Outbound Webhook.

📘

Note

For Email Channel, the events marked with Asterisk are applicable only if 'Email via AWS SES' is the selected route.

5. Enable Hub Signature (Optional Configuration) - The signature is the hexadecimal (40-byte) representation of the signature computed using the HMAC algorithm selected during configuration (E.g., one of SHA256 or SHA 512) as defined in RFC2104. When enabled, you will receive an additional header called x-hub-signature. The signing of Webhooks (also known as, enabling hub signature) is recommended under best security practices. Webhook signatures help ensure that a webhook payload was sent by Webex Connect and was not tampered with. The value of the hub secret is used as the key to creating a signature of the notification data and is sent along with the notification, which can then be verified by the receiving server.
   A sample Python script for checking the signature is added in the FAQs section. Click here to view the sample script.
6. Enable Authorisation (Optional Configuration) - Select the Authorization that you would like to apply to this Outbound Webhook Configuration. Adding an Authorisation to the outbound webhook is advised under best security practices. It allows the notification-receiving endpoint to make sure the request is posted from the authorized platform (i.e. Webex Connect). Authorizations are added under Integrations. Please refer to the section on Authorization Configuration below for more information.
7. When you select a phone number from the Entity drop-down and select Incoming Message, the Forward to SMPP checkbox becomes visible if you don't select Enable Hub Signature. When you select the Forward to SMPP checkbox you also need to select a value from Select ESME Bind ID drop-down list.

7. Click Save.

Configuring Outbound Webhook at Apps Level

To configure an outbound webhook for a given app on Webex Connect platform, perform the following steps:

1. Click Add Integration > Outbound Webhook.
2. Enter Name for your outbound webhook configuration.
3. Select Entity to which you want to associate your outbound webhook at App level. It must be an In-App app asset.

4. Select the checkboxes for the notifications you want to receive.

5. Click Save.

How to use Outbound Webhooks to forward delivery receipts

To receive delivery receipts for your outbound messages:

1. Select a service from the Entity dropdown
2. Select the outbound channel for which you want to receive the delivery receipts
3. Select the receipt types you want the notifications for. Please note that different channels offer different kinds of receipts.
   The below table shows which notifications are available for each channel supported by Webex Connect. By default, none of the notifications are selected. You must explicitly select the required notifications channel-wise.

Sample Payloads for Outbound Message Status and Incoming Messages

📘

Sample Payloads

For Information related to the sample payloads, refer to the section Outbound Webhooks in the API Reference documentation. Please note that the payloads vary for each message type, each event type, and each channel. Also, enhancements are made to these payloads overtime as new message types or events are added and/or existing ones are updated or deprecated. Please keep your application at the receiving end flexible to avoid any impact when such changes are made.

Error Codes

📘

Error Codes

For Information related to the common and channel-specific error codes, refer to the section Channel Specific Status Codes in the API Reference documentation.

For more information on Authorization for Outbound Webhook, refer here.

Export Logs for Outbound Webhooks Failed Notifications

Notification to an endpoint can fail because of multiple reasons, for example - the Endpoint not being reachable, Authorisation failed, Too many requests, etc. On encountering a failure, Webex Connect tries to successfully post the request to the endpoint three times, after 60 seconds. After three retries, Webex Connect drops the notification requests as failed notifications.

You can download or export the list of all the failed notifications to SFTP/S3 locations using the Export Logs configuration.

📘

Note

The failed notification logs are available only in New Export Logs, not Legacy Export Logs.

This feature allows you to download or export logs for Incoming messages, Message receipts failed notifications configured through Outbound Webhooks.

This does not include notifications sent through Reserved keywords, Contact Policy APIs, Flow Notifications configured under Flow settings, Data Stream etc.

FAQ

Below is a sample Python script for checking the signature.

import hashlib
import hmac
#rawData is the payload and signatureHeader is the header received in the notificaiton post request (Please note to trim all white spaces in the rawData and
#signature header contains only the value of  x-hub-signature without sha256=
rawData = '{"deliveryInfoNotification":{"deliveryInfo":{"timeStamp":"2024-03-04T18:24:17.284Z","Description":"Submitted","code":"7501","deliveryChannel":"email","additionalInfo":"","destination":[email protected],"destinationType":"email","deliveryStatus":"Submitted"},"subtid":"","transid":"8388899605-56e9-46b0-861e-44af7ee10391","callbackData":"This is callbackdata","correlationid":""}}'
signatureHeader = "12345678901234567890ijklmnoqrstuvwxyz1234567890c9c034044e6558980"
#Secret used in the outbound webhook configuration
secret = "abcdefgh1234567890ijklmnoqrstuvwxyz1234567890"
#if using sha512 use hashlib.sha512
sha = hashlib.sha256
newHmac = hmac.new(secret.encode(), rawData.encode(), sha).hexdigest()
print(newHmac)
if(signatureHeader == newHmac):
                print("Header verified")
else:
                print("Header NOT verified")