> For the complete documentation index, see [llms.txt](https://help.cerby.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook.md). # Create a webhook This article describes how to create a webhook endpoint in Cerby to receive real-time signed HTTPS notifications. {% hint style="info" %} **Who can use this feature?** * Workspace **Owners**, **Super Admins**, and **Admins** * Supported using the Cerby web app {% endhint %} As a workspace **Owner**, **Super Admin**, or **Admin**, you can create webhook endpoints to receive real-time signed HTTPS notifications when account and automation events occur in your workspace. You can create multiple webhooks, each subscribed to a different set of event types. ## Requirements This procedure requires the following: * A Cerby workspace with the webhooks feature turned on * An HTTPS endpoint you control that can receive POST requests from Cerby ## Steps To create a webhook, you must complete the following steps: 1. [Configure the webhook details](#1-webhook-details) 2. [Select the events](#2-select-events) 3. [Choose the signing method](#3-signing-method) 4. [Copy your signing key](#4-copy-your-signing-key) The following sections describe each step. ## 1. Webhook details Complete the following steps to start the wizard and configure your webhook: 1. Log in to your [Cerby](https://app.cerby.com/) workspace. 2. Select **Settings** from the left navigation. The **Workspace Configuration** page is displayed. 3. Select the **Webhooks** left tab. 4. Click the **Create webhook** button. The **Create new webhook** page is displayed. 5. Enter a name for the webhook in the **Name** field. The name can be up to 100 characters. 6. Enter your endpoint URL in the **Endpoint URL** field. The URL must start with `https://` and cannot exceed 2,048 characters.

NOTE: If your endpoint URL is a Slack Incoming Webhook at hooks.slack.com, Cerby delivers a Slack Block Kit message instead of the standard JSON envelope. For details on the format and the field subset it carries, refer to the "Sending to a Slack Incoming Webhook" section of Implement a webhook receiver.

7. (Optional) Enter a description in the **Description** field. The description cannot exceed 512 characters. 8. Click the **Next** button. The **Select events** page is displayed. ## 2. Select events Complete the following steps to select the events Cerby sends to your endpoint: 1. Select the event types you want to subscribe to. You can select individual event types, or apply one of the following presets from **Quick select**: * **Audit-only:** Subscribes to every available event type except the actionable ones, that is, the events a compliance team records but that do not need remediation. * **Failures-only:** Subscribes to the actionable events, which are `account.credentials.rotation_failed`, `account.credentials.breach_detected`, `account.login.failed`, `account.mfa.setup_failed`, and `automation.failed`. * **Everything:** Subscribes to all available event types. * **Clear all:** Clears your current selection. You must select at least one event type to continue.

NOTE: The Failures-only preset includes account.credentials.breach_detected because it asks you to act, even though its name does not end in failed. For what that event carries, refer to Handle breach detection events.

NOTE: An event type labeled Not delivered is open for subscription, but Cerby does not send it yet. You can select it to have the subscription in place ahead of delivery, and Cerby delivers to everyone already subscribed as soon as the event ships. The Everything and Audit-only presets both include it.

2. Click the **Next** button. The **Signing method** page is displayed. ## 3. Signing method Complete the following steps to choose how Cerby signs each request: 1. Select a signing algorithm: * **Ed25519** (recommended): Uses asymmetric signing. Cerby generates a key pair and returns your public key after the webhook is created. You store the public key and use it to verify signatures. * **HMAC-SHA256:** Uses symmetric signing. Cerby generates a shared secret and returns it after the webhook is created. You store the shared secret and use it to verify signatures. You cannot change the signing algorithm later. To use a different algorithm, delete the webhook and create a new one. 2. Click the **Create webhook** button. The webhook is created and your signing key material is displayed. ## 4. Copy your signing key {% hint style="danger" %} **IMPORTANT:** Copy your signing key material before leaving this page. Cerby displays the key only once. If you leave without copying it, you must rotate the signing key to obtain new key material. {% endhint %} Complete the following steps to store your signing key: 1. Copy the key material displayed: * **Ed25519:** Copy the **Public key** value and store it securely. You use this key to verify the `X-Cerby-Signature` header on incoming webhook requests. * **HMAC-SHA256:** Copy the **Signing secret** value and store it securely. You use this secret to verify the `X-Cerby-Signature` header on incoming webhook requests. Your receiver needs this value to verify every delivery. 2. Click the **Done** button. The new webhook appears in the **Webhooks** list. Now you are done. ## Related articles **Feature guides:** * [Explore webhook notifications](/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications.md) * [Edit a webhook](/setup-and-admin/workspace-settings/webhooks/edit-a-webhook.md) * [Delete a webhook](/setup-and-admin/workspace-settings/webhooks/delete-a-webhook.md) * [Test a webhook endpoint](/setup-and-admin/workspace-settings/webhooks/test-a-webhook-endpoint.md) **Developer reference:** * [Implement a webhook receiver](https://help.cerby.com/developer-tools/cerby-webhooks/implement-a-webhook-receiver) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.