API Reference

Hookly's REST API gives you programmatic access to your endpoints and events — list what's configured, pull recent activity, and trigger replays from your own tooling or CI pipelines.

Authentication

Every request must include an API key as a bearer token. Create one from Settings → API Keys — the plaintext key is shown once at creation and can't be retrieved again. Keys are scoped to the team that created them and can be revoked at any time. API access is available on Pro and Enterprise plans — keys created on those plans stop working if the team downgrades.

curl https://hookly.dev/api/v1/endpoints \
  -H "Authorization: Bearer hk_live_..."

Rate limits

The public webhook receiver (/api/ingest/:endpointId) is limited to 300 requests per 60 seconds per endpoint. Requests over the limit receive a 429 with a Retry-After header. The endpoints below are not currently rate limited beyond your plan's usage.

Errors

Errors are returned as JSON with an error string and a matching HTTP status.

{ "error": "Invalid or missing API key" }

401Missing, invalid, or revoked API key

403Your team's plan doesn't include API access

404Resource doesn't exist or doesn't belong to your team

500Something went wrong on our end

List endpoints

GET/api/v1/endpoints

Returns every endpoint configured for your team, newest first.

curl https://hookly.dev/api/v1/endpoints \
  -H "Authorization: Bearer hk_live_..."

Response

{
  "data": [
    {
      "id": "ceeba64c-9d05-4ee6-9048-3bb7d4c7cc09",
      "name": "Stripe Payments",
      "service": "stripe",
      "destination_url": "https://api.example.com/webhooks/stripe",
      "status": "active",
      "last_run_at": "2026-07-12T21:58:07.187Z",
      "last_status": "relayed",
      "created_at": "2026-07-01T10:00:00.000Z"
    }
  ]
}

List events

GET/api/v1/events

Returns recent events for your team, newest first.

Query parameters

endpoint_idFilter to a single endpoint

limitMax results, default 50, capped at 200

curl "https://hookly.dev/api/v1/events?limit=20" \
  -H "Authorization: Bearer hk_live_..."

Response

{
  "data": [
    {
      "id": "b7608276-4c47-424d-bc8d-390b095a7fee",
      "endpoint_id": "ceeba64c-9d05-4ee6-9048-3bb7d4c7cc09",
      "received_at": "2026-07-12T21:58:07.187Z",
      "method": "POST",
      "event_type": "payment_intent.succeeded",
      "status": "relayed",
      "signature_valid": true,
      "size_bytes": 812,
      "replayed": false,
      "replay_of": null
    }
  ]
}

Get an event

GET/api/v1/events/:id

Returns full event detail, including headers, body, and every relay attempt made against it.

curl https://hookly.dev/api/v1/events/b7608276-4c47-424d-bc8d-390b095a7fee \
  -H "Authorization: Bearer hk_live_..."

Response

{
  "data": {
    "id": "b7608276-4c47-424d-bc8d-390b095a7fee",
    "endpoint_id": "ceeba64c-9d05-4ee6-9048-3bb7d4c7cc09",
    "received_at": "2026-07-12T21:58:07.187Z",
    "source_ip": "203.0.113.4",
    "method": "POST",
    "request_headers": { "content-type": "application/json", "...": "..." },
    "request_body": "{ ... }",
    "signature_valid": true,
    "verification_error": null,
    "status": "relayed",
    "event_type": "payment_intent.succeeded",
    "size_bytes": 812,
    "replayed": false,
    "replay_of": null,
    "relay_attempts": [
      {
        "id": "9075199e-9c79-4c84-8603-01f466cf588d",
        "attempt_number": 1,
        "response_status": 200,
        "response_headers": { "...": "..." },
        "response_body": "OK",
        "duration_ms": 143,
        "error": null,
        "attempted_at": "2026-07-12T21:58:07.523Z"
      }
    ]
  }
}

Replay an event

POST/api/v1/events/:id/replay

Re-sends the original request to the endpoint's destination URL and creates a new event linked back to the original via replay_of.

curl -X POST https://hookly.dev/api/v1/events/b7608276-4c47-424d-bc8d-390b095a7fee/replay \
  -H "Authorization: Bearer hk_live_..."

Response

{
  "data": {
    "id": "9075199e-9c79-4c84-8603-01f466cf588d",
    "success": true,
    "responseStatus": 200,
    "error": null
  }
}

Get started free