Webhooks

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

Authentication · Errors · Amounts and 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

Response · 201

Field	Type	Required	Description
object	string	Yes
data	Webhook	Yes
meta	object	No

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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[]	Yes
meta	ListMeta	Yes

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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[]	Yes
meta	ListMeta	Yes

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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	Yes
meta	object	No

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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	Yes
meta	object	No

For failed requests, inspect error.code, error.message and the request ID. Error handling.