Outbound webhooks
Last Update: Sep 2024 • Est. Read Time: 3 MINWebhooks let you connect two applications and automatically sync data between them. Outbound webhooks send events from Kustomer to other systems. They accept unique URLs and send data in JSON format as events occur in Kustomer.
Webhooks are best suited for server-to-server communication where verifying the sender's authenticity is important. In Kustomer, posting to a webhook requires a Kustomer API key with the org.permission.outbound_webhook
permission. Learn more about creating and using API keys in the Kustomer Developer Portal: Kustomer REST APIs
Who can access this feature? | |
User types | Admins can access the Outbound webhooks settings page. |
In this article
Create an outbound webhook
You can set up to 5 outbound user-created webhooks up at any time in your Kustomer organization.
Note: Webhooks allow organizations to send events and their related data payloads from the Kustomer app to third-party applications. Since this method grants your data to external parties, exercise caution and due diligence when researching providers to ensure that the recipient will handle your data responsibility.
To create an outbound webhook:
- Go to Settings > Platform > Outbound webhooks.
- Select Add Outbound Webhook.
- Enter a name for the webhook, which is how you'll identify this hook throughout the Kustomer platform.
- Then, fill in the Destination URL. This is the inbound webhook URL for the application that will receive data from Kustomer.
- Next, choose which Kustomer events trigger the webhook to send data. Use the Webhook Trigger Events to set any number of the following Kustomer events:
- Conversation Create
- Conversation Update
- Customer Create
- Customer Update
- Message Create
- Message Update
- Team Create
- Team Update
- User Create
- User Update
- Select Save Changes in the bottom toolbar.
Learn more about outbound webhook content in our Developer Portal in: Kustomer Apps Platform: Sample trigger event payloads.
Webhook secrets
Kustomer uses a webhook secret to ensure that the webhook is signed and verified. The secret is created once you add a new outbound webhook.
Kustomer's outbound webhooks have a SHA256 HMAC signature in their X-Kustomer-Webhook-Signature
request headers. When creating a token via the API using POST /v1/outbound-webhooks
, the return body contains a token
field that contains the secret we use for the HMAC signature. You can use this secret to validate the HMAC signature on the receiving end.
To validate a signature:
Here's an example of validating the webhook signature using JavaScript.
const crypto = require('crypto'); // kustomerSecret can be found in Outbound Webhook UI const computedSignature = crypto .createHmac('sha256', kustomerSecret) .update(httpBody) .digest('hex'); // receivedSignature is in X-Kustomer-Webhook-Signature header if (computedSignature === receivedSignature) { // request was signed by Kustomer };
In the above JS example, the key
is the outbound webhook's token
field. You'll locate the kustomerSecret
in the Outbound Webhooks Settings.
To view a webhook's secret:
- Go to Settings > Platform > Outbound webhooks.
- Locate the desired webhook and select Edit.
- Scroll down to the Header Information section.
Note: The secret is only generated after you initially save a webhook. If you're currently creating a new webhook, you'll need to save it first, then reopen the editor to access the secret.
Manage your existing outbound webhooks
You can manage all of your outbound webhooks from one page. Select Settings> Platform > Outbound Webhooks to access a list of your configured outbound webhooks.
Turn off a webhook
You can deactivate a webhook by turning off the toggle on this page. A webhook will also be automatically turned off if it is revoked or not working.
Edit a webhook
You can edit an existing webhook by selecting it. Once you have made any necessary edits, select Save Changes.
Delete a webhook
You can edit your existing webhooks by selecting Delete or Edit and then Delete from its page.
Retry policy
We attempt to send an event 10 times over an approximately 80-minute timeframe. If an outbound webhook request is unsuccessful 10 times in a row, the webhook will be turned off and must be turned on again manually. After this occurs, please return to the Outbound webhook page to verify everything is set up correctly, then turn it back on when it's ready to be used.