# Outbound webhooks

> Webhooks let you connect two applications and automatically sync data between them. Outbound webhooks are used to send events from Kustomer to other systems....

Source: https://help.kustomer.com/en_us/outbound-webhooks-rkUQvela8

Last updated: 2026-07-06T19:34:55.611Z

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 essential. 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](https://developer.kustomer.com/kustomer-api-docs/reference/introduction#api-keys-authentication)

**Who can access this feature?**

**User types**

Admins can access the Outbound webhooks settings page.

### In this article

*   [Create an outbound webhook](#create-an-outbound-webhook)
*   [Available webhook events](#available-webhook-events)
*   [Webhook payload structure](#webhook-payload-structure)
*   [Webhook auto-disable behavior](#webhook-auto-disable-behavior)
*   [Webhook secrets](#webhook-secrets)
*   [Manage your existing outbound webhooks](#manage-your-existing-outbound-webhooks)
*   [Understand outbound webhook error notifications](#understand-outbound-webhook-error-notifications)
*   [Automatic webhook disabling](#automatic-webhook-disabling)
*   [Troubleshoot webhook errors](#troubleshoot-webhook-errors)
*   [Automatic webhook disabling (platform safety)](#automatic-webhook-disabling-2)

### Create an outbound webhook

You can set up outbound user-created webhooks 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 responsibly.

**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](https://developer.kustomer.com/kustomer-apps-platform/docs/outbound-webhooks#sample-trigger-event-payloads).

### Available webhook events

You can configure outbound webhooks for the following event types: **Conversation**, **Customer**, **Message**, **Team**, and **User** events.

Org-level events such as `org.user.login`, `org.permission.update`, `app.install`, and `app.uninstall` are **not available** for outbound webhooks.

### Webhook payload structure

Outbound webhook payloads are predefined and always send the complete event object in JSON format. You cannot filter, customize, or modify which fields the payload includes. Workflows also cannot alter the webhook payload structure before delivery.

To work with a subset of the payload data, transform or filter the payload on the receiving end before passing it downstream.

For sample trigger event payloads by event type, see the [outbound webhooks developer documentation](https://developer.kustomer.com/kustomer-apps-platform/docs/outbound-webhooks#sample-trigger-event-payloads).

### Webhook auto-disable behavior

Kustomer automatically disables an outbound webhook after 10 consecutive failed requests. Failed requests include timeout errors (such as `ESOCKETTIMEDOUT`), non-2xx responses, and connection errors. The auto-disable typically triggers over approximately 80 minutes of consecutive failures.

Once disabled, the webhook stops sending events until you manually re-enable it.

**To re-enable a disabled webhook:**

1.  From the left navigation, click **Settings**. The Settings page opens.
2.  In the **Settings** page, click **Platform**, then select **Webhooks**.
3.  Locate the disabled webhook and toggle it back on.

**To prevent future auto-disables:**

*   Ensure your receiving endpoint returns a 2xx status code within a few seconds of receiving the request.
*   Process webhook payloads asynchronously — accept the request immediately, return 200, then process the payload in a background job.
*   Check your server for firewall, VPN, or DNS rules that may block incoming requests from Kustomer.
*   Monitor your endpoint's availability and response time.

**Note:** There is currently no automatic notification when a webhook is disabled. Check your webhook status periodically, or monitor your integration's data flow for gaps that may indicate a disabled webhook.

### 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.

![Header Information section](https://cdn.kustomerhostedcontent.com/media/570fad9d9001bc1000163b28/694c4e8a5febc9260ef904ff435f4d16.png)

**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 the edit icon. Once you have made any necessary edits, select **Save Changes**.

**Delete a webhook**

You can delete your existing webhooks by selecting **Delete** or selecting **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.

### Understand outbound webhook error notifications

Kustomer sends error notification emails when an outbound webhook receives a non-2xx response from the external endpoint, even if a subsequent retry succeeds. This means you may receive an error email for a transient issue (such as a 502 response) that was automatically resolved.

**Why errors may not appear in the UI:** If the retry succeeded, the webhook status displays as "sent successfully" in the org logging page. The error notification email reflects the initial failure, not the final outcome.

**To investigate webhook errors:**

1.  From the left navigation, select **Settings**, then select **Platform** > **Org Logging**. Search for entries containing "error" in the time range of the notification.
2.  For detailed error information, make a GET request to the `/v1/logs/search/outbound-webhook` API endpoint with the relevant time range.

### Automatic webhook disabling

If the receiving endpoint fails to respond successfully 10 consecutive times (over approximately 80 minutes), Kustomer automatically disables the webhook. This prevents repeated failed deliveries from affecting system performance.

When a webhook is auto-disabled:

*   The webhook status changes to **Off** in **Settings > Platform > Outbound Webhooks**.
*   No notification is sent to administrators. Check webhook status regularly or monitor your receiving endpoint for errors.

To re-enable a disabled webhook:

1.  Investigate and resolve the issue with the receiving endpoint (for example, server downtime, expired credentials, or changed URL).
2.  From the left navigation, click **Settings**. The Settings page opens.
3.  In the **Settings** page, click **Platform**, then select **Outbound Webhooks**.
4.  Locate the disabled webhook and toggle it back to **On**.

### Troubleshoot webhook errors

If you receive webhook error notification emails, use the following approaches to diagnose the issue.

**View detailed logs via the API**

The Settings > Org Logging page provides a high-level view. For granular error details, send a `GET` request to:

`GET /v1/logs/search/outbound-webhook`

Include a time range parameter to scope the results.

**Common causes of webhook failures**

*   The receiving endpoint is experiencing downtime.
*   Credentials or authentication tokens on the receiving endpoint have expired.
*   The webhook URL has changed or is incorrect.
*   The receiving endpoint is rejecting requests due to payload format or size.

**Auto-disable behavior**

If a webhook fails **10 consecutive times** over approximately 80 minutes, Kustomer automatically disables it. The webhook status changes to **Off** in **Settings > Platform > Outbound Webhooks**. No administrator notification is sent when a webhook is auto-disabled.

To re-enable a webhook, fix the underlying endpoint issue, then toggle the webhook back to **On** in **Settings > Platform > Outbound Webhooks**.

### Automatic webhook disabling (platform safety)

Kustomer automatically disables an outbound webhook after 10 consecutive failed delivery attempts within approximately 80 minutes. This is a platform-wide safety measure and cannot be changed or disabled.

Common failure causes include:

*   The receiving server is not responding (`ESOCKETTIMEDOUT` errors).
*   Network instability or firewall/proxy rules blocking requests.
*   The receiving server is overloaded.

After a webhook is disabled, you must manually re-enable it from **Settings > Platform > Outbound Webhooks**.

To receive notifications about webhook errors, add email addresses in **Settings > Platform > Org Logging > Notifications** tab.