# Webhooks

Register endpoints, manage subscriptions and inspect delivery attempts.

This is the simulated Earn API. Position creation and withdrawal change sandbox records; they do not sign a wallet transaction.


[Authentication](/build/authentication/) · [Errors](/build/errors/) · [Amounts and units](/build/units/)


## Register a webhook endpoint

`POST /webhooks`


Registers an endpoint. The URL is SSRF-guarded (loopback, private, link-local and metadata addresses are rejected). The signing secret is returned once.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `Idempotency-Key` | header | `string` | No | Client-generated key. Retries with the same key replay the original response. |


### Request body

Schema: [CreateWebhookRequest](/api/sandbox-models/#createwebhookrequest)


### Response · 201

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [Webhook](/api/sandbox-models/#webhook) | Yes |   |
| `meta` | `object` | No |   |


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## List webhook endpoints

`GET /webhooks`


Lists endpoints with masked signing secrets.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `limit` | query | `integer` | No | Page size (1-500, default 100) |

| `cursor` | query | `string` | No | Opaque cursor returned as meta.next_cursor |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |   |
| `data` | [Webhook](/api/sandbox-models/#webhook)[] | Yes |   |
| `meta` | [ListMeta](/api/sandbox-models/#listmeta) | Yes |   |


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Webhook delivery log

`GET /webhooks/events`


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `webhook_id` | query | `string` | No | Filter by webhook |

| `limit` | query | `integer` | No | Page size (1-500, default 100) |

| `cursor` | query | `string` | No | Opaque cursor returned as meta.next_cursor |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |   |
| `data` | [Delivery](/api/sandbox-models/#delivery)[] | Yes |   |
| `meta` | [ListMeta](/api/sandbox-models/#listmeta) | Yes |   |


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Delete a webhook endpoint

`DELETE /webhooks/{id}`


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes | Webhook id |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [DeletedWebhook](/api/sandbox-models/#deletedwebhook) | Yes |   |
| `meta` | `object` | No |   |


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Send a test event

`POST /webhooks/{id}/test`


Dispatches a synthetic system.status event and returns the delivery record.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `id` | path | `string` | Yes | Webhook id |

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [Delivery](/api/sandbox-models/#delivery) | Yes |   |
| `meta` | `object` | No |   |


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).