> ## Documentation Index > Fetch the complete documentation index at: https://docs.contraforce.com/llms.txt > Use this file to discover all available pages before exploring further. # Setting Up Webhooks > Create, secure, test, and manage outbound webhooks that send ContraForce incident and Gamebook events to your own systems. A webhook sends a signed HTTPS request to an endpoint you control every time a selected event happens in ContraForce, such as an incident being created, closed, or commented on. Use webhooks to push incidents into your ticketing system, SIEM, chat tools, or automation platform without polling the API. **Who is this for?** Organization Admins and security engineers connecting ContraForce to an external system. For the payload of each event, see the [Webhook Event Reference](/api-reference/webhook-events). ## Before you start * You are signed in as an **Organization Admin**. * You have an HTTPS endpoint that accepts `POST` requests and answers with a `2xx` status within 30 seconds. Plain HTTP, `localhost`, and private network addresses are rejected. * You know how your endpoint expects to authenticate callers: no authentication, basic authentication, or a bearer token. ## Choose an authentication type Every delivery is signed with an HMAC-SHA256 signature in the `X-CF-Signature` header, whichever option you pick. The authentication type adds an `Authorization` header on top of that signature for endpoints that require one. | Authentication | What ContraForce sends | Use it when | | ------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | **No authentication** | No `Authorization` header. The request is verified by its `X-CF-Signature` only. | Your endpoint verifies the signature itself, or it is a URL with a secret token built in. | | **Basic authentication** | `Authorization: Basic ` | Your endpoint or gateway expects a username and password. | | **Bearer token** | `Authorization: Bearer ` | Your endpoint or API gateway expects an API key or token. | ## Create a webhook In the left navigation, click **Settings**, then select the **Developers** tab. The **Integrations** list shows your existing webhooks and service accounts. Settings page with the Developers tab selected, showing the Integrations list and the Add integration button Click **Add integration**. In the panel that opens, open the **Integration type** list and select **Webhook**. Add integration panel with the Integration type list open, showing Webhook and Service account Under **Webhook details**, enter a **Name** that tells your team where the events go (for example, `SOC ticketing webhook`) and the **URL** of your endpoint, such as `https://hooks.company.example/contraforce`. Then open the **Authentication** list and choose the type your endpoint expects. Webhook details with Name and URL filled in and the Authentication list open, showing No authentication, Basic authentication, and Bearer token What you fill in depends on the type you picked. Nothing else to enter. Verify the `X-CF-Signature` header on your endpoint so it only accepts requests from ContraForce. Enter the **Username** and **Password** your endpoint expects. Both are required. Basic authentication selected, with Username and Password fields Enter the **Token** your endpoint expects. It is sent as `Authorization: Bearer `. **Signing token** is optional. Leave it empty and ContraForce generates a signing secret for you when you save. Enter a value only if you want to supply the key used to sign `X-CF-Signature` yourself. Bearer token selected, with a required Token field and an optional Signing token field Under **Events**, turn on each event this webhook should receive. At least one is required. * Turn on **Webhook Test** if you want to use **Send test** later to check connectivity. * For close handling, pick **Incident Closed** *or* **Incident Status Changed**. A close fires both, so subscribing to both gives you two deliveries per close. Events list with Incident Created, Incident Closed, and Incident Comment Added turned on Click the info icon next to any event to see a sample payload exactly as your endpoint will receive it. Use **Copy JSON** to build and test your parser before any real event arrives. Incident Created sample payload dialog showing the JSON envelope, with Copy JSON and Close buttons Under **Workspaces**, search for and add the customer workspaces this webhook should send events for. Leave the list empty to send events from **all** workspaces you manage, including ones you add later. The **Agent investigation completed** event is listed separately as **Owned by another flow**. You don't subscribe to it here: it is wired from an agent's classification card. See [Send agent verdicts to a webhook](#send-agent-verdicts-to-a-webhook). Owned by another flow callout for Agent investigation completed, and the Workspaces section with an empty workspace search Click **Save**. ContraForce shows the webhook's **signing secret** once. Copy it with the copy button and store it in your endpoint's secret store, then click **Done**. The signing secret is not shown again after you close this dialog. If you lose it, open the webhook and click **Regenerate**, then update your endpoint with the new secret. Webhook signing secret dialog with the secret value hidden, a copy button, and a Done button If you entered your own **Signing token** for a bearer-token webhook, the dialog tells you that token is used for signing instead. The new webhook appears in the **Integrations** list with the **Webhook** type and an **Active** status. Integrations list showing the new SOC ticketing webhook with Webhook type and Active status ## Send a test and check the delivery Test before you rely on the webhook, and again any time you change the endpoint or its credentials. In **Settings → Developers**, click the gear icon on the webhook's row. The **General** tab shows the endpoint, authentication, signing secret, event subscriptions, and workspaces. Webhook details General tab with Pause and Delete buttons, the Endpoint section, the Authentication section with Update credentials, and the Signing secret section with Regenerate Under **Event subscriptions**, click **Send test** on the **Webhook Test** row. A **Test webhook queued for delivery** message confirms the request was queued. Event subscriptions section with Webhook Test turned on and a Send test button Test deliveries carry an `X-CF-Test: true` header and `"isTest": true` in the body, so your endpoint can tell them apart from real events. Select the **Events** tab. Each delivery attempt is listed with its date, workspace, event type, and status. A test that reached your endpoint shows **Success**. Delivery events list showing a webhook.test.v1 delivery with Success status Click the eye icon on a row to see the HTTP status code your endpoint returned, the latency, the attempt number, and any error message. Event run details dialog showing webhook.test.v1, Success status, API response 200, latency 449 ms, and attempt 1 The delivery log stores delivery metadata only, not the body that was sent. For incident events, the details show the incident as it is now, fetched from the source. See [Delivery logs](/api-reference/webhook-events#delivery-logs). ## Manage an existing webhook Everything below is on the webhook's **General** tab unless noted. | To do this | Do this | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Stop deliveries temporarily | Click **Pause**. Click **Resume** to start again. | | Change the name, URL, events, or workspaces | Edit the field, then click **Save changes**. | | Rotate credentials | Click **Update credentials** in the **Authentication** section. Existing credentials are never shown. | | Rotate the signing secret | Click **Regenerate** in the **Signing secret** section, then update your endpoint with the new secret. | | Re-enable an auto-disabled webhook | Fix the endpoint, then click **Enable**. A webhook is disabled automatically after 5 or more distinct incidents fail final delivery within 24 hours. | | Resend a failed incident delivery | On the **Events** tab, open the failed entry and redeliver it. See [Redelivery](/api-reference/webhook-events#redelivery). | | Remove the webhook | Click **Delete**. | ## Send agent verdicts to a webhook The **Agent investigation completed** event (`agent.investigation.completed.v1`) is not a subscription. It fires only when an agent's classification card names this webhook as its custom action. You can create the webhook from the card itself, and it is subscribed to the event automatically when you save. See [Configuring Security Delivery Agents](/guides/getting-started/configuring-security-delivery-agents) to set it up, and [Agent Investigation Completed Webhook](/guides/agent-center/agent-investigation-webhook) for the payload. ## Troubleshooting | Symptom | Likely cause | Fix | | -------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Save** reports the URL is invalid | The URL is plain HTTP, `localhost`, or a private address | Use a public HTTPS endpoint. | | Test delivery shows **Failed** with `401` or `403` | Your endpoint rejected the credentials | Click **Update credentials** and re-enter them, then send another test. | | Delivery shows **Failed** with a timeout | Your endpoint took longer than 30 seconds | Return a `2xx` immediately and process the event asynchronously. | | Your endpoint rejects the signature | The wrong secret, or the body was parsed before verifying | Verify against the raw request body with the current secret. See [Verifying the Signature](/api-reference/webhook-events#verifying-the-signature). | | No events arrive, but tests succeed | The event is not turned on, or the workspace is not in the webhook's list | Check **Event subscriptions** and **Workspaces** on the **General** tab. | | The webhook status is **Disabled** | Repeated final delivery failures triggered auto-disable | Fix the endpoint, send a test, then click **Enable**. | ## Related guides Every event type, the delivery envelope, headers, retries, and signature verification. Receive and verify agent verdicts from a classification card. Call the ContraForce API from your automation. The classifications and reasons carried on closed incidents. Need help? Contact [support@contraforce.com](mailto:support@contraforce.com).