> ## 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.

# Manage webhook endpoints

> Create and manage workspace webhook endpoints with an OAuth access token.

OAuth integrations can manage webhook endpoints in the workspace selected
during authorization. Use the workspace public ID returned by
[`GET /oauth/me`](/docs/api-reference/oauth/connection); do not ask the user to
enter it.

All requests use the OAuth access token as a Bearer credential:

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
```

## Endpoints and scopes

These routes use the full `https://biq.li/api` base URL rather than the
versioned Links API base URL.

| Action | Method and path | Required scope |
| :- | :- | :- |
| List endpoints | `GET /workspace/{workspace}/webhooks` | `webhooks.view` |
| Create an endpoint | `POST /workspace/{workspace}/webhooks` | `webhooks.create` |
| Retrieve an endpoint | `GET /workspace/{workspace}/webhooks/{webhook}` | `webhooks.view` |
| Update an endpoint | `PATCH /workspace/{workspace}/webhooks/{webhook}` | `webhooks.update` |
| Enable or disable | `POST /workspace/{workspace}/webhooks/{webhook}/toggle` | `webhooks.update` |
| Send a test event | `POST /workspace/{workspace}/webhooks/{webhook}/test` | `webhooks.update` |
| List deliveries | `GET /workspace/{workspace}/webhooks/{webhook}/deliveries` | `webhooks.view` |
| Retrieve a delivery | `GET /workspace/{workspace}/webhooks/{webhook}/deliveries/{delivery}` | `webhooks.view` |
| Delete an endpoint | `DELETE /workspace/{workspace}/webhooks/{webhook}` | `webhooks.delete` |

Scopes do not replace workspace policy checks. The approving user must still
be a workspace member and allowed to perform the operation.

## Create an endpoint

```bash theme={null}
curl --request POST \
  --url https://biq.li/api/workspace/biq_ws_EXAMPLE/webhooks \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Production events",
    "url": "https://app.example.com/webhooks/biqli",
    "events": ["link.created", "link.updated", "sale.created"]
  }'
```

`name` is required and accepts up to 80 characters. `url` is required and
accepts up to 2,048 characters. `events` must contain between one and six
distinct [supported event types](/webhooks/event-types).

The response returns `201 Created`. Copy the signing secret immediately and
store it in a server-side secret manager:

```json theme={null}
{
  "webhook": {
    "id": "wh_01M39EXAMPLE000000000000",
    "name": "Production events",
    "receiver": "oauth",
    "url": "https://app.example.com/webhooks/biqli",
    "secret": "whsec_REDACTED",
    "events": ["link.created", "link.updated", "sale.created"],
    "enabled": true
  }
}
```

The secret is included only when the caller can configure the endpoint. Treat
it like a password. Use it to [verify every delivery](/webhooks/verify-signatures).

## Update or toggle an endpoint

`PATCH` uses the same `name`, `url`, and `events` payload as creation. Send the
complete desired configuration.

Enable or disable an endpoint separately:

```json theme={null}
{
  "enabled": false
}
```

Disabling an endpoint stops new production events. It does not remove delivery
history, and test deliveries remain available for diagnosis.

## Send a test event

```bash theme={null}
curl --request POST \
  --url https://biq.li/api/workspace/biq_ws_EXAMPLE/webhooks/wh_01M39EXAMPLE000000000000/test \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"event":"link.created"}'
```

The endpoint returns `202 Accepted` with a pending delivery. Test deliveries
set `is_test` to `true` and pass through the same signing and retry pipeline as
production deliveries.

## Inspect deliveries

The delivery list accepts `per_page` from 10 to 100 and returns page metadata.
The delivery detail includes the request payload, response body, and recorded
attempts. A delivery includes its event ID, event type, status, attempt count,
HTTP status, error message, timestamps, and `is_test` flag.

## URL and ownership rules

* A destination must be a publicly reachable HTTP or HTTPS URL.
* Embedded credentials, localhost, and private or reserved addresses are rejected.
* A workspace cannot register the same normalized URL twice.
* OAuth-created endpoints belong to that OAuth connection.
* Revoking the connection removes the endpoints owned by it.
* An endpoint or delivery from another workspace returns `404`.

For event envelopes, signature verification, retries, and receiver behavior,
continue with the [Webhooks guide](/webhooks/introduction).