See related
No related articles

Outbound webhooks

Last Update: Sep 2024 • Est. Read Time: 3 MIN
To check plan availability, see the pricing page.

Webhooks 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 typesAdmins 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:

  1. Go to Settings > Platform > Outbound webhooks.
  2. Select Add Outbound Webhook.
  3. Enter a name for the webhook, which is how you'll identify this hook throughout the Kustomer platform.
  4. Then, fill in the Destination URL. This is the inbound webhook URL for the application that will receive data from Kustomer.
  5. 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
  6. 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:

  1. Go to Settings > Platform > Outbound webhooks.
  2. Locate the desired webhook and select Edit.
  3. 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.