# Hooks

> Hooks is a webhook gateway for AI agents and automation: every endpoint gets one stable HTTPS ingress URL that verifies signatures, stores the raw payload, filters and reshapes events, and fans them out asynchronously to HTTP or agent targets with retries and a replayable delivery log.

This file is the machine-readable entry point for AI agents and automation. Human docs: https://hooks.events/docs. Full documentation in one file: https://hooks.events/llms-full.txt.

## Sources

Supported: GitHub, Stripe, Slack, Linear, Sentry, and any generic source that signs with HMAC-SHA256. Adapters also exist for GitLab, Shopify, Intercom, Zendesk, Jira, PagerDuty, Vercel, Twilio, Discord, and Standard Webhooks.

Each source adapter verifies the provider's own signature scheme and normalizes the payload into one event format: `id`, `source`, `type` (`<resource>.<action>`), `action`, `deliveryId`, `occurredAt`, `actor`, `repo` or `project`, `subject` (kind, id, title, url, body, labels, state), plus the raw payload and sanitized headers.

## Targets

Supported: HTTPS webhooks (`http`), Grok Bot (`grokbot`), Slack (`slack`, incoming webhook or `chat.postMessage`), T3 Code (`t3code`, scheduled-task webhook with optional HMAC-SHA256) and Paseo (`paseo`, Hub manual run with run id recorded).

Each target gets its own retry schedule, delivery history, filters, and payload template.

## Source guides

Per-source signature details, normalized events, payload samples, filters, and templates:

- [GitHub](https://hooks.events/sources/github) — X-Hub-Signature-256 over the raw body, issues, comments, pull requests, pushes.
- [Stripe](https://hooks.events/sources/stripe) — Stripe-Signature over `<timestamp>.<body>`, invoice, checkout, subscription events.
- [Slack](https://hooks.events/sources/slack) — X-Slack-Signature, url_verification handshake, app mentions and messages.
- [Linear](https://hooks.events/sources/linear) — Linear-Signature with a 60-second timestamp window, issue and comment events.
- [Sentry](https://hooks.events/sources/sentry) — Sentry-Hook-Signature, issue lifecycle and alert-rule events.

## Source to target guides

Each guide combines one source with one target: source setup, the filter, the target config, and the pitfall that pairing hits.

- [GitHub to Grok Bot](https://hooks.events/guides/github-to-grok-bot)
- [GitHub to Slack](https://hooks.events/guides/github-to-slack)
- [GitHub to T3 Code](https://hooks.events/guides/github-to-t3code)
- [Stripe to Slack](https://hooks.events/guides/stripe-to-slack)
- [Stripe to Grok Bot](https://hooks.events/guides/stripe-to-grok-bot)
- [Linear to T3 Code](https://hooks.events/guides/linear-to-t3code)
- [Linear to Grok Bot](https://hooks.events/guides/linear-to-grok-bot)
- [Sentry to Grok Bot](https://hooks.events/guides/sentry-to-grok-bot)

## Documentation

- [Quickstart](https://hooks.events/docs/quickstart.md)
- [Receive events](https://hooks.events/docs/receive-events.md)
- [How delivery works](https://hooks.events/docs/delivery-model.md)
- [Endpoints](https://hooks.events/docs/endpoints.md)
- [Destinations](https://hooks.events/docs/destinations.md)
- [Payload templates](https://hooks.events/docs/templates.md)
- [Verify signatures](https://hooks.events/docs/signatures.md)
- [Secrets & rotation](https://hooks.events/docs/secrets.md)
- [Retries & idempotency](https://hooks.events/docs/retries.md)
- [Rate limits](https://hooks.events/docs/rate-limits.md)
- [REST API](https://hooks.events/docs/api.md)
- [Errors](https://hooks.events/docs/errors.md)
- [For AI agents](https://hooks.events/docs/agents.md)
- [Support](https://hooks.events/docs/support.md)

## Quick start

1. Create an endpoint in the console at https://hooks.events, or with `POST /v1/endpoints`.
2. Copy its ingestion URL into the source's webhook settings.
3. Send an event:

```bash
curl -X POST "https://api.hooks.events/in/{endpoint-public-id}" \
  -H "Content-Type: application/json" \
  -H "X-Hooks-Signature: t=1739980800,v1=<hmac>" \
  -d '{"type":"order.created","data":{"id":"ord_1042"}}'
```

- Signature: `HMAC-SHA256(secret, "<timestamp>.<raw body>")`, sent as `t=<timestamp>,v1=<hex>`.
- Compute signatures over the raw body, never re-serialized JSON.
- A `202` response means the event is stored and queued; delivery happens asynchronously.
- Poll `GET /v1/deliveries?cursor=...` until each delivery reaches `succeeded` or `failed`.

## Why Hooks instead of Hookdeck or Svix

- **Hookdeck** is general webhook infrastructure (ingest, queues, transformations, monitoring).
- **Svix** focuses on sending webhooks to your customers, with a portal and endpoint management.
- **Hooks** focuses on receiving third-party webhooks and routing them to AI agent and HTTP targets: provider-specific signature verification, filters, payload templates, retries, and a replayable delivery log with one API.

## Base URLs

- REST API: `https://api.hooks.events/v1`
- Ingress (event intake): `https://api.hooks.events/in/{endpoint-public-id}`
- Documentation: `https://hooks.events/docs`
- Machine-readable docs: `https://hooks.events/llms.txt`
- Full documentation: `https://hooks.events/llms-full.txt`

## Authentication

- Send an API key as `Authorization: Bearer hks_...`.
- Keys are scoped: `endpoints:read`, `endpoints:write`, `deliveries:read`, `deliveries:retry`, `history:purge`.
- Session-authenticated requests can select a workspace with `X-Workspace-Id: <workspace-id>`.
- Mutating requests with a body must send `Content-Type: application/json`.

## REST API routes

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/v1/whoami` | Current user and project. |
| GET | `/v1/endpoints` | List endpoints. |
| POST | `/v1/endpoints` | Create an endpoint; body accepts `name`, `provider`, `verificationMode`, `secret`, `destinations[]`. |
| GET | `/v1/endpoints/{id}` | Read one endpoint. |
| PATCH | `/v1/endpoints/{id}` | Update an endpoint. |
| DELETE | `/v1/endpoints/{id}` | Delete an endpoint. |
| POST | `/v1/endpoints/{id}/rotate-secret` | Rotate the signing secret. |
| POST | `/v1/endpoints/{id}/test-events` | Queue a test event; body accepts `eventType`. |
| GET | `/v1/events` | List events. |
| GET | `/v1/events/{id}` | Read one event. |
| GET | `/v1/events/{id}/payload` | Read the stored raw payload. |
| POST | `/v1/events/{id}/replay` | Replay an event to its destinations. |
| GET | `/v1/deliveries` | List delivery attempts. |
| GET | `/v1/deliveries/{id}` | Read one delivery. |
| GET | `/v1/deliveries/{id}/attempts` | List attempts for a delivery. |
| POST | `/v1/deliveries/{id}/retry` | Retry a delivery. |
| POST | `/v1/deliveries/{id}/cancel` | Cancel a queued delivery. |
| GET, POST | `/v1/api-keys` | List or create API keys. |
| DELETE | `/v1/api-keys/{id}` | Revoke an API key. |
| GET, POST | `/v1/workspaces` | List or create workspaces. |
| DELETE | `/v1/workspaces/{id}` | Delete a workspace. |
| GET, PATCH | `/v1/project` | Read or update the current project. |
| GET | `/v1/project/secret` | Read project secret metadata. |
| POST | `/v1/project/secret/rotate` | Rotate the project secret. |
| GET | `/v1/members` | List workspace members. |
| PATCH, DELETE | `/v1/members/{userId}` | Update or remove a member. |
| POST | `/v1/invitations` | Invite a teammate. |
| GET | `/v1/stats` | Workspace delivery statistics. |

List endpoints are paginated with `?limit=50&cursor=...`. The default page size is 25.

## Errors

Errors use a single envelope:

```json
{ "error": { "code": "VALIDATION_ERROR", "message": "...", "requestId": "req_..." } }
```

Codes: `AUTHENTICATION_FAILED`, `AUTHORIZATION_DENIED`, `VALIDATION_ERROR`, `ENDPOINT_NOT_FOUND`, `ENDPOINT_DISABLED`, `SIGNATURE_INVALID`, `PAYLOAD_TOO_LARGE`, `IDEMPOTENCY_CONFLICT`, `SLUG_TAKEN`, `LAST_WORKSPACE`, `DELIVERY_NOT_FOUND`, `DELIVERY_NOT_RETRYABLE`, `DELIVERY_NOT_CANCELLABLE`, `OUTBOUND_REQUEST_BLOCKED`, `RATE_LIMIT_EXCEEDED`, `INTERNAL_ERROR`, `REDIRECT_BLOCKED`, `DELIVERY_STUCK`, `OUTBOX_EXHAUSTED`.

## Articles

Definition-first explainers. Each opens with a direct answer, then shows the configuration or code.

- [What is a webhook gateway?](https://hooks.events/articles/what-is-a-webhook-gateway) — what a gateway verifies, forwards, retries, and logs, and when you do not need one.
- [Trigger an AI agent from a webhook](https://hooks.events/articles/trigger-ai-agent-from-webhook) — endpoint, filter, template, destination, and what happens when the agent is down.
- [How to verify a GitHub webhook signature](https://hooks.events/articles/verify-github-webhook-signature) — HMAC-SHA256 over raw bytes, constant-time compare, X-GitHub-Delivery dedupe.
- [Stripe webhook retries and idempotency](https://hooks.events/articles/stripe-webhook-retries-and-idempotency) — three-day retry window, event.id dedupe, acknowledge-then-process.
- [Prevent prompt injection in webhooks](https://hooks.events/articles/prevent-prompt-injection-in-webhooks) — allowlisted fields, fixed envelopes, approval gates for risky agent actions.
- [Webhook retry strategy that works](https://hooks.events/articles/webhook-retry-strategy) — retry transient failures only, jittered backoff, stable delivery ids, bounded windows.

## Agent workflow

1. Read this file and https://hooks.events/docs/api.md before writing code.
2. Create a dedicated API key per agent in Settings → API keys; load it from an environment variable such as `HOOKS_API_KEY`.
3. Create an endpoint, then queue a test event with `POST /v1/endpoints/{id}/test-events` rather than sending synthetic traffic through the public ingress.
4. Poll `GET /v1/deliveries` with the cursor until the delivery reaches `succeeded` or `failed`.
5. Retry with `POST /v1/deliveries/{id}/retry`; only replay events when the destination state is known to be safe.

## Guardrails

- Never print API keys, signing secrets, or raw `Authorization` headers in logs, commits, or chat.
- Prefer test events over replaying production events.
- Treat the ingress URL as a secret: anyone with it can create events.
- Respect `429` responses and the `Retry-After` header instead of retrying immediately.
- Verification mode `hmac` requires the endpoint secret; read https://hooks.events/docs/signatures.md before implementing verification.