> For the complete documentation index, see [llms.txt](https://detected.gitbook.io/detected-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://detected.gitbook.io/detected-docs/api-overview/webhooks/setup.md).

# Setup

## Enabling webhooks

To enable webhooks navigate to the integration information section of the case management. Select the required webhooks and input the following:

* Webhook URL = the URL that you'd like to receive the webhook
* Webhook Secret (optional) = a string used to sign the webhook request

{% hint style="info" %}
If you are using standalone KYC flows within Detected (using profiles of type individuals) then we'd also recommend enabling the setting to automatically update the profile status on submission of a KYC flow. This way you can utilise the webhooks for both KYB and KYC profiles. This setting can be found in case management on the 'Customer portal->Settings' page.
{% endhint %}

## Verifying webhooks using secrets (optional)

To add an extra layer of security you can provide a secret that can be used by your downstream systems to verify the webhook.

Processing logic:

1. Read the raw request body (before JSON parsing).
2. Read the Signature header.
3. Compute HMAC-SHA256 and compare.

### Examples

| Value                         | Source                  | Where it comes from                                                                      |
| ----------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
| Your webhook secret           | You (dashboard)         | Integration Information → Webhook Secret. Should also be stored securely in your system. |
| Raw webhook request body      | Detected (inbound POST) | Exact HTTP body — do not re-parse or re-serialize JSON.                                  |
| Signature header from webhook | Detected (inbound POST) | HTTP header name is "Signature" (capital S). Value is 64-char lowercase hex.             |

```python
import hashlib
import hmac

# webhook_secret    -> YOUR secret from dashboard (Webhook Secret field)
# raw_body          -> RECEIVED raw HTTP body from Detected POST
# signature_header  -> RECEIVED value of header "Signature" (capital S)
def verify_detected_webhook(raw_body, webhook_secret, signature_header):
    expected = hmac.new(
        webhook_secret.encode('utf-8'),
        raw_body.encode('utf-8'),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header.strip())

# webhook_secret = os.environ['WEBHOOK_SECRET']
# raw_body = request.get_data(as_text=True)
# signature_header = request.headers.get('Signature', '')
```

### Common mistakes

| Mistake                               | Result                                 |
| ------------------------------------- | -------------------------------------- |
| SHA256(body + secret) plain hash      | Verification fails — use HMAC-SHA256   |
| Re-serialize JSON after parsing       | Verification fails — use raw body      |
| Base64-encode the digest              | Verification fails — use lowercase hex |
| Wrong secret (different webhook type) | Verification fails                     |

## Webhook timeout and retries

Webhooks by default are fire and forget.

## Whitelisting IPs

If your firewall requires whitelisting of IPs to receive the webhooks please contact us to get the required IP addresses.


---

# 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://detected.gitbook.io/detected-docs/api-overview/webhooks/setup.md?ask=<question>&goal=<user_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.