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

# Create a webhook

> Creates a signed webhook that receives Guard alerts by `POST` with a JSON body.

Body: `{"url": "https://…", "scope": "mine", "watch_id": null, "min_severity": "high", "description": "…"}`.

- `scope`: which alerts it receives.
 - `mine` (the default): those of the watches owned by the person who creates it.
 - `org`: those of the organization's shared watches, not each person's private ones. An administrator of the
 organization creates it, and it stops receiving if that person is no longer active in the organization.
 - `watch`: those of one watch and its derived watches, given in `watch_id`. Created by someone who can edit
 that watch.
- `min_severity`: the minimum severity that is notified (`low`, `medium`, `high` or `critical`); `high` by
 default.
- `url`: `https`, on port 443, without user or password and with a host that resolves to public IP addresses. It
 is validated when the webhook is created and on every delivery.

Up to 10 webhooks per organization.

Returns the webhook with the full `secret` **only once** (`secret_shown_once: true`). After that, the secret is
shown masked.

**Messages.** One `POST` is sent per alert and per event. `type` is `guard.alert.created` (a new alert),
`guard.alert.retracted` (a chain reorganization removed the transaction), `guard.alert.revived` (the
transaction was included again), `guard.alert.updated` (a person changed the alert) or `guard.test`. The body
includes `type`, `timestamp`, `api_version` and `data`, with `alert` (the same `facts` as
`GET /v1/guard/alerts/{aid}` and `status` at the time of delivery), `watch` and `webhook`. `guard.alert.updated`
adds `data.change`, with who made the change and which fields changed; for a comment, it only states that one was
added. The body does not include email addresses or names of people.

**Signature** ([Standard Webhooks](https://www.standardwebhooks.com/)). Each message carries three headers:
- `webhook-id`: the message id. It is the same on every retry; use it to avoid processing a message twice.
- `webhook-timestamp`: the time of delivery, in unix seconds.
- `webhook-signature`: `v1,<base64>`, the HMAC-SHA256 of `"{webhook-id}.{webhook-timestamp}.{body}"`. The key is
 the base64 bytes that follow `whsec_` in the secret.

To verify a message: compute the signature over the raw body, before parsing the JSON; compare it in constant
time with each `v1,…` in the header; reject a `webhook-timestamp` more than 5 minutes off, and discard a
`webhook-id` already processed. The Standard Webhooks libraries perform this verification with the same secret.

**Delivery.** Any `2xx` response counts as delivered. On any other response or no response, delivery is retried
after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h and 8 h (about 15 hours in total), with the same `webhook-id`;
after that, the delivery becomes `failed`. A notification that could not be sent within 3 days expires
(`expired`). Order is preserved within the same alert, but not across different alerts: use `data.alert.id` and
`timestamp`. A `410 Gone` response or 30 consecutive failures disable the webhook. Redirects are not followed.

Errors:
- `400`: invalid or non-public URL, invalid scope or severity, `scope: "watch"` without `watch_id`, or `watch_id`
 with another scope.
- `403`: the `org` scope without being an administrator of the organization, a watch the requester cannot edit,
 the webhook limit reached, or an API key not assigned to a person.
- `404`: a watch the requester cannot view.
- `422`: the body contains an unknown field.

**Cost:** free.



## OpenAPI

````yaml /openapi.en.json post /v1/guard/webhooks
openapi: 3.1.0
info:
  title: blockgence API
  description: >-
    The **blockgence** API provides fund tracing, entity attribution and
    explainable risk screening across several

    networks, with the evidence behind every result.


    ### Authentication

    Every `/v1/*` route requires an **API key**, sent in the `X-API-Key: <key>`
    header or as

    `Authorization: Bearer <key>`. Your organization issues the key. The
    evidence verification routes

    (`/v1/evidence/*`) do not require a key.


    ### Credits and limits

    Each plan has a **per-minute request limit** and a **monthly credit
    allowance**. Each operation states its cost in

    credits. **Only successful responses (status below 400) are charged:** an
    error response is recorded with 0

    credits. Check your usage with `GET /v1/account`.


    ### Data that could not be read

    If the data source cannot read what you requested, the response is `503
    source_unavailable`, with no charge,

    stating the source, the network, the query, the reason and whether a retry
    is advisable. If an intermediate step

    fails, the response is 200 and declares it in `degraded_sources` and in the
    `coverage_gaps` of the node or edge:

    in those cases, missing data does not mean missing activity.


    ### Networks

    `ethereum`, `bsc`, `polygon`, `arbitrum`, `base` and `optimism`; plus `tron`
    for tracing, profile, funding, network

    probing and transactions. `GET /v1/chains` states what can be queried on
    each network, at no cost. The networks

    `monero`, `bitcoin`, `litecoin` and `solana` are recognized in `/screening`
    and `/address`, where the network is

    inferred from the address format. Any other network returns `400`: it is
    never replaced with Ethereum.
  contact:
    name: blockgence
    url: https://www.blockgence.com/
  version: 1.0.0
servers:
  - url: https://app.blockgence.com
    description: Production
security: []
tags:
  - name: Platform
    description: >-
      Available networks, what can be queried on each one, from which sources
      and under which methodology. No cost.
  - name: Tracing
    description: >-
      Fund-flow tracing and reads of an address or a transaction: a
      time-consistent graph in both directions, funding, counterparties,
      bridges, swaps, mixers, labels and on-chain data.
  - name: Screening
    description: >-
      Risk screening of an address, with a recommendation (allow, review or
      block), its reasons and its sources.
  - name: Contracts
    description: Contract inspection and simulation of a transaction before signing it.
  - name: Tokens
    description: Token profile, with its issuer, supply, holders and risk signals.
  - name: Compromise
    description: >-
      Compromise vector of a stolen wallet, that is, how control of the funds
      was lost.
  - name: Incidents
    description: >-
      Incident response for victims, hacks and scams: playbook, freeze requests
      to issuers, post-mortem and deliverables.
  - name: Copilot
    description: >-
      AI investigation copilot that answers in natural language and cites the
      evidence (SSE streaming).
  - name: Cases
    description: >-
      Investigation cases to save, share and export, with their evidence,
      activity and annotations.
  - name: Permissions
    description: >-
      Approvals, delegations and signatures that grant access to an address's
      funds (ERC-20, Permit2 and EIP-7702).
  - name: Guard
    description: Wallet and protocol monitoring, with alerts by webhook and email.
  - name: Travel Rule
    description: >-
      Travel Rule without third-party connections: ownership challenge,
      counterparty, reconciliation and validation of IVMS101 messages.
  - name: Audit
    description: >-
      Smart contract audits, with the status, findings and evidence of each
      audit.
  - name: Evidence
    description: >-
      Verification of sealed evidence, with the signing public key and
      timestamps. No API key or charge required.
  - name: Monero
    description: >-
      Public profile of a Monero transaction and verification of a payment
      proof. Monero does not publish senders or amounts, so it is not traced.
  - name: Account
    description: Usage and limits of your API key.
  - name: Icons
    description: Entity logos to render graphs in your own interface. No cost.
  - name: Service
    description: Service status.
paths:
  /v1/guard/webhooks:
    post:
      tags:
        - Guard
      summary: Create a webhook
      description: >-
        Creates a signed webhook that receives Guard alerts by `POST` with a
        JSON body.


        Body: `{"url": "https://…", "scope": "mine", "watch_id": null,
        "min_severity": "high", "description": "…"}`.


        - `scope`: which alerts it receives.
         - `mine` (the default): those of the watches owned by the person who creates it.
         - `org`: those of the organization's shared watches, not each person's private ones. An administrator of the
         organization creates it, and it stops receiving if that person is no longer active in the organization.
         - `watch`: those of one watch and its derived watches, given in `watch_id`. Created by someone who can edit
         that watch.
        - `min_severity`: the minimum severity that is notified (`low`,
        `medium`, `high` or `critical`); `high` by
         default.
        - `url`: `https`, on port 443, without user or password and with a host
        that resolves to public IP addresses. It
         is validated when the webhook is created and on every delivery.

        Up to 10 webhooks per organization.


        Returns the webhook with the full `secret` **only once**
        (`secret_shown_once: true`). After that, the secret is

        shown masked.


        **Messages.** One `POST` is sent per alert and per event. `type` is
        `guard.alert.created` (a new alert),

        `guard.alert.retracted` (a chain reorganization removed the
        transaction), `guard.alert.revived` (the

        transaction was included again), `guard.alert.updated` (a person changed
        the alert) or `guard.test`. The body

        includes `type`, `timestamp`, `api_version` and `data`, with `alert`
        (the same `facts` as

        `GET /v1/guard/alerts/{aid}` and `status` at the time of delivery),
        `watch` and `webhook`. `guard.alert.updated`

        adds `data.change`, with who made the change and which fields changed;
        for a comment, it only states that one was

        added. The body does not include email addresses or names of people.


        **Signature** ([Standard Webhooks](https://www.standardwebhooks.com/)).
        Each message carries three headers:

        - `webhook-id`: the message id. It is the same on every retry; use it to
        avoid processing a message twice.

        - `webhook-timestamp`: the time of delivery, in unix seconds.

        - `webhook-signature`: `v1,<base64>`, the HMAC-SHA256 of
        `"{webhook-id}.{webhook-timestamp}.{body}"`. The key is
         the base64 bytes that follow `whsec_` in the secret.

        To verify a message: compute the signature over the raw body, before
        parsing the JSON; compare it in constant

        time with each `v1,…` in the header; reject a `webhook-timestamp` more
        than 5 minutes off, and discard a

        `webhook-id` already processed. The Standard Webhooks libraries perform
        this verification with the same secret.


        **Delivery.** Any `2xx` response counts as delivered. On any other
        response or no response, delivery is retried

        after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h and 8 h (about 15 hours
        in total), with the same `webhook-id`;

        after that, the delivery becomes `failed`. A notification that could not
        be sent within 3 days expires

        (`expired`). Order is preserved within the same alert, but not across
        different alerts: use `data.alert.id` and

        `timestamp`. A `410 Gone` response or 30 consecutive failures disable
        the webhook. Redirects are not followed.


        Errors:

        - `400`: invalid or non-public URL, invalid scope or severity, `scope:
        "watch"` without `watch_id`, or `watch_id`
         with another scope.
        - `403`: the `org` scope without being an administrator of the
        organization, a watch the requester cannot edit,
         the webhook limit reached, or an API key not assigned to a person.
        - `404`: a watch the requester cannot view.

        - `422`: the body contains an unknown field.


        **Cost:** free.
      operationId: create_webhook_v1_guard_webhooks_post
      parameters:
        - name: X-Case-Id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Case-Id
          description: >-
            Active case, optional: the token of a case you can view. The query
            is recorded in that case and also uses its own labels. A case that
            does not exist, was deleted or is no longer shared with you returns
            `400 case_unavailable` and the query is not run, with no charge.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema: {}
        '401':
          description: The API key is missing, invalid or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: The monthly credits are exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            The request does not have the expected shape; `detail` states which
            field to correct.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            The per-minute request limit was exceeded. Retry after the number of
            seconds in `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - APIKeyHeader: []
        - BearerAuth: []
components:
  schemas:
    WebhookCreate:
      properties:
        url:
          type: string
          title: Url
        scope:
          type: string
          title: Scope
          default: mine
        watch_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Watch Id
        min_severity:
          type: string
          title: Min Severity
          default: high
        description:
          type: string
          title: Description
          default: ''
      additionalProperties: false
      type: object
      required:
        - url
      title: WebhookCreate
    Error:
      type: object
      title: Error
      description: >-
        Common shape of errors: a readable `detail` and, in many cases, an
        `error` with a stable code to recognize it without parsing the text.
      properties:
        detail:
          type: string
          description: What happened, in one sentence.
        error:
          type: string
          description: Stable error code, when there is one.
      required:
        - detail
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key in the `X-API-Key` header.
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        The same API key as `Authorization: Bearer <key>`, as an alternative to
        `X-API-Key`.

````

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