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

# Introduction

> Receive signed Biqli events at your server as they happen.

Webhooks let Biqli notify your server when a workspace event occurs. Instead of repeatedly asking Biqli for changes, your application exposes an endpoint and Biqli sends an HTTP request to it.

## Supported events

| Event          | Sent when                                     |
| :------------- | :-------------------------------------------- |
| `link.created` | A short link is created                       |
| `link.updated` | A tracked link field or configuration changes |
| `link.deleted` | A short link is deleted                       |
| `link.clicked` | A verified human link click is persisted      |
| `lead.created` | Conversion tracking creates a lead            |
| `sale.created` | Conversion tracking creates a sale            |

## How delivery works

1. You create a webhook endpoint in **Workspace settings -> Webhooks**.
2. You select one or more event types.
3. Biqli creates an event after the product change commits.
4. Biqli sends a signed JSON `POST` request to your URL.
5. Your server verifies the signature and event identity.
6. Your server stores or queues the event and returns HTTP `2xx`.

## Common envelope

Every request has the same outer shape:

```json theme={null}
{
  "id": "evt_01m2example000000000000000",
  "event": "lead.created",
  "createdAt": "2026-09-14T13:40:24+00:00",
  "data": {}
}
```

| Field       | Meaning                                                    |
| :---------- | :--------------------------------------------------------- |
| `id`        | Unique delivery event identity; store it for deduplication |
| `event`     | Event type used to select the payload contract             |
| `createdAt` | UTC time when Biqli created the webhook event              |
| `data`      | Event-specific object documented in the Events section     |

## Delivery headers

```http theme={null}
Content-Type: application/json
User-Agent: Biqli-Webhooks/1.0
Biqli-Signature: <lowercase HMAC-SHA256 hex digest>
Biqli-Event-Id: evt_01m2example000000000000000
Biqli-Event: lead.created
```

Always verify `Biqli-Signature` against the exact raw body before processing the JSON.

## Important guarantees and responsibilities

* Biqli can deliver an event more than once. Deduplicate with the envelope `id`.
* Events can arrive later than the product action because delivery is queued.
* Return `2xx` only after your system has safely accepted the event.
* Process expensive work asynchronously after acceptance.
* Do not depend on delivery order across different events.
* Keep the signing secret private and rotate it by replacing the endpoint if compromised.

Continue with [Create an endpoint](/webhooks/create-endpoint), then implement [signature verification](/webhooks/verify-signatures).