> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bodyguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your webhook

> Register a webhook in the Bodyguard dashboard to receive notifications on your endpoint.

A webhook notifies your endpoint when events occur in Bodyguard, such as a message or an author being updated. This page walks you through registering one in the dashboard. To learn how webhooks work, see the [Webhooks introduction](https://docs.bodyguard.ai/en/api-reference/webhooks/introduction.md).

## Prerequisites

You need a public HTTPS endpoint that is ready to receive notifications. Bodyguard denies webhooks registered with an `http` URL. See the [Quick start](https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start.md) to build your endpoint and verify the signature of each request.

## Steps

**1. Add a webhook**

1. Click the gear icon in the left menu to open **Settings**, select **Webhooks**, then click **Add webhook**.

   ![Webhooks page with the Settings gear icon (1), the Webhooks entry (2), and the Add webhook button (3) highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/01-open-webhooks-page.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=71ad72d9f89c307321eb2981a9acf4c9)

   Settings > Webhooks

2. Fill in the form. The numbers match the screenshot below.

   **1.** Enter the **Endpoint URL** that receives notifications. It must be publicly reachable over HTTPS.\\

   **2.** Add at least one **Alert contact**. Bodyguard notifies your contacts when deliveries to this endpoint fail. Each contact must be a user registered to your organization on the dashboard.\\

   **3.** Choose the **Sources** the webhook applies to. In this example, **All the organization's API sources** is selected.\\

   **4.** Select the **Events** you subscribe to: `message.updated` (when a message is updated by Bodyguard) and `author.updated` (when an author is updated by Bodyguard).\\

   **5.** Click **Create webhook**.

   ![New webhook dialog with the Endpoint URL (1), Alert contact (2), Sources (3), and Events (4) fields and the Create webhook button (5) highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/02-new-webhook-form.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=b3c06997e442288a625613943e370d37)

   New webhook form

   See [Configuration](https://docs.bodyguard.ai/en/api-reference/webhooks/configuration.md) for each field and [Payloads](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads.md) for the content of each event.

   > [!NOTE]
   >
   > When you create the webhook, Bodyguard sends a [`webhook.validate`](https://docs.bodyguard.ai/en/api-reference/reference/webhooks/payloads#webhook-validate) event to your endpoint. Your endpoint must answer it with a `2xx` status code.

**2. Copy your signing secret**

Bodyguard generates a signing secret when you create the webhook and displays it in the **Webhook created** dialog. Copy it with the copy icon and store it somewhere safe, then click **Done**. The secret starts with `whsec_`.

![Webhook created dialog with the signing secret field and its copy icon highlighted](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/03-signing-secret.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=3c03ea994fe4205b5afd49160524df63)

Signing secret displayed at creation

> [!WARNING]
>
> The signing secret is shown only once. You can't see it again after closing the dialog. Treat it like a password and never expose it in client-side code.

You use the signing secret to verify that each request comes from Bodyguard. See the [Quick start](https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start.md).

**3. Enable and test your webhook**

Your webhook is created with the `Disabled` status. Enable it once your endpoint is ready to receive events. Click the **⋮** menu at the end of the webhook row to open its actions:

![Webhooks list with the three-dot button of the webhook row (1) and its actions menu highlighted, showing Send test event, Edit webhook, Enable webhook, and Delete webhook](https://mintcdn.com/bodyguardai/oGCRxEeuFI_d_hrR/images/how-to/connect-webhook/04-webhook-actions-menu.png?fit=max\&auto=format\&n=oGCRxEeuFI_d_hrR\&q=85\&s=f6f543e38882a16540b4c21afdfa074c)

Webhook actions menu

* **Enable webhook** activates the webhook.
* **Send test event** lets you check that your endpoint receives events.
* **Edit webhook** and **Delete webhook** let you change or remove the webhook.

> [!NOTE]
>
> While a webhook is disabled, Bodyguard doesn't send its events, and they can't be replayed when you enable the webhook again. See [Webhook statuses](https://docs.bodyguard.ai/en/api-reference/webhooks/configuration.md#webhook-statuses).

## Next steps

> [card] [Quick start](https://docs.bodyguard.ai/en/api-reference/webhooks/quick-start.md)
>
> Build an endpoint and verify each request with a Standard Webhooks library.

> [card] [Configuration](https://docs.bodyguard.ai/en/api-reference/webhooks/configuration.md)
>
> Events, signing secret, contacts, and webhook statuses.

> [card] [Handling errors](https://docs.bodyguard.ai/en/api-reference/webhooks/handling-errors.md)
>
> What happens when your endpoint fails, and how to recover.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.