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. subject to channel specific capabilities.)
• Incoming calls and messages from customers across channels
• 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 we have added support for SHA256 and SHA512 signatures while setting up outbound webhooks. SHA1 signature option that was earlier available is no longer supported and cannot be used for new outbound webhook configurations.

📘

Note

The SHA-1 feature is no longer supported for new configurations. The feature will work as is for the existing configurations.

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 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. 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.
6. Select the Authorization that you would like to apply to this Outbound Webhook Configuration. 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.

Adding Authorization for Outbound Webhook Notifications

❗️

Please note that feature is not working for SMS and Voice channels due to a bug that has been fixed in v6.4.1. v6.4.1 is currently live only on Webex Connect Ireland and Canada instances. For other sites, please wait for v6.4.1 to be deployed before using this feature for these two channels.

To add a new authorization, follow the below steps:

1. Navigate to Assets → Integrations.
2. Click Add Authorization.
3. Enter a name for the authorization.
4. Select the Type of authorization and configure the details. You must configure the following parameters based on the authorization type:
   1. No Auth – select this type when you do not need an authorization
   2. Basic Auth – select this type when you need to do an authorization using username and password

c. Digest Auth - select this option when you need to validate the user identity before sending any sensitive information like online banking transactional details. In this type of authorization, a network server receives the request from a user and then sends it to a domain controller. The domain controller responds with a special session key.

d. AWS Signature - select this option when you want to use the Amazon Work Services workflow for authorization. You must use a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication.

e. API Key - Enter the Key and Key Value.

f. OAuth 2.0 – is a well-adopted delegated authorization framework. Supports two different grant types for OAuth 2.0.

1. Authorization code - server issues the token in the context of a user.
2. Client credentials - grant type is used to obtain an access token outside of the context of a user.

5. Click Save.
   The created authorization will be displayed in the list of authorizations which you can associate with the desired Outbound Webhook configuration.