Webhooks

Endpoint management only. The event payload, the signature scheme and the delivery caveats are in Webhooks.

Register an endpoint

POST /v1/webhooks

Success: 201.

curl -sX POST https://api.farthing.ai/v1/webhooks \
  -H "authorization: Bearer $FARTHING_KEY" \
  -H 'content-type: application/json' \
  -d '{"url":"https://hooks.example.com/farthing","label":"prod"}'

string

required

Must be https://. http://localhost and http://127.0.0.1 are accepted for local development; nothing else over plain HTTP is.

string

Optional, max 200 characters. Yours, for telling endpoints apart in the list.

Response (201)

{
  "id": "c81b0d5e-4a71-4a1e-9a2f-6f83b1c04e29",
  "url": "https://hooks.example.com/farthing",
  "label": "prod",
  "secret": "whsec_kR7pXvT2mQ9fLbN4hJ8sYc1WdE6aZg0u"
}

secret is returned exactly once, here. It is the only thing that lets you verify a delivery is genuinely from us. There is no rotate endpoint — see rotating a secret.

400 Invalid request with issues on a non-https URL or a malformed body. Multiple endpoints per tenant are supported, each with its own secret. Every active endpoint receives every event.

List endpoints

GET /v1/webhooks

Success: 200.

curl -s https://api.farthing.ai/v1/webhooks \
  -H "authorization: Bearer $FARTHING_KEY"

{
  "data": [
    {
      "id": "c81b0d5e-4a71-4a1e-9a2f-6f83b1c04e29",
      "url": "https://hooks.example.com/farthing",
      "label": "prod",
      "lastDeliveryAt": "2026-07-29T09:26:29.881Z",
      "lastDeliveryStatus": 200,
      "createdAt": "2026-07-28T14:03:55.204Z"
    }
  ],
  "nextCursor": null
}

Read data, for the same reason as on GET /v1/api-keys: it is the field checkouts and buyer profiles already answer with. The response repeats the identical array as endpoints, the field’s original name, elided from the example for length and kept for existing callers. nextCursor is always null — there is nothing to page. Newest first, and revoked endpoints are excluded.

string | null

When we last attempted a delivery. null until the first one.

integer | null

The raw HTTP status your endpoint returned. The fastest way to notice you have been 500ing for a day.

Secrets are never returned by this endpoint.

Revoke an endpoint

DELETE /v1/webhooks/{id}

Success: 200.

curl -sX DELETE https://api.farthing.ai/v1/webhooks/$ENDPOINT_ID \
  -H "authorization: Bearer $FARTHING_KEY"

{ "revoked": true }

Deliveries stop immediately and the endpoint disappears from the list. Revocation is a timestamp, not a row delete, so the delivery history is preserved. 404 Endpoint not found if it does not exist, is not yours, or is already revoked.

Reference

Endpoints

Register an endpoint

List endpoints

Revoke an endpoint

​Register an endpoint

​List endpoints

​Revoke an endpoint

Register an endpoint

List endpoints

Revoke an endpoint