# Litehook

> Litehook is a webhook gateway. Each sender is a "source" with its own ID and secret. A source's flow checks and shapes each event, then sends a notification to the workspace's devices, forwards the event to HTTPS endpoints, or both.

## Send an event

New sources are signed by default and accept events at one endpoint, using Standard Webhooks headers:

POST https://litehook.app/api/v1/sources/SOURCE_ID/events
Content-Type: application/json
webhook-id: msg_UNIQUE_ID
webhook-timestamp: UNIX_SECONDS
webhook-signature: v1,BASE64_SIGNATURE

{"title": "Deploy finished", "message": "api v2.3 is live", "level": "success", "group": "deploys"}

Signing:
- The signing secret looks like "whsec_" followed by base64. Read it from an environment variable such as LITEHOOK_SECRET.
- webhook-id: unique per event; a retry of the same event reuses it and is acknowledged without being stored again.
- webhook-timestamp: Unix seconds, within 5 minutes of the server's time.
- webhook-signature: "v1," + base64 HMAC-SHA256 of "WEBHOOK_ID.WEBHOOK_TIMESTAMP.BODY", keyed with the base64-decoded secret after "whsec_". BODY is the exact bytes sent.
- Use a Standard Webhooks library where one exists.

Fields:
- title: string, required in practice, up to 120 characters. Falls back to "event", then the source name.
- message: string, optional, up to 2000 characters. "body" is also accepted.
- level: "info" (default), "success", "warning" or "error". "success": true/false sets success or error when level is absent.
- group: string, optional, up to 80 characters. Repeats with the same group collapse in the inbox and replace each other on the phone.

Signed sources also accept plain text and form data, as the source allows.

## Sources with Signed requests turned off (URL token)

For senders that cannot sign, such as Coolify or Home Assistant, a source created with Signed requests off accepts JSON at two addresses:

- POST https://litehook.app/api/ingest/SOURCE_ID with Authorization: Bearer SECRET
- POST https://litehook.app/hook/SOURCE_ID/SECRET, for services that only accept a URL. Treat the whole URL as a secret.

These take the same JSON fields, plus idempotency_key: string, optional, up to 120 characters. A repeat for the same source is acknowledged as {"duplicate": true} and not stored again.

## Responses

- 202: accepted. Signed endpoint: {"accepted": true, "event_id": "...", "duplicate": false}. URL-token addresses: {"accepted": true, "id": 123, "event_id": "..."}, or {"accepted": true, "duplicate": true}.
- 400: the body cannot be parsed, or a field is invalid; the error explains.
- 401: wrong, missing or rotated secret or signature, or the source is unknown. On the URL-token addresses a disabled or deleted source looks the same.
- 403: the workspace is paused, or the sender's address is not on the source's allowlist.
- 404: malformed URL.
- 409: a signed source that has never been published, or a webhook-id reused with a different body.
- 410: a signed source with receiving turned off.
- 413: body over 64 KiB.
- 415: content type not accepted (URL-token sources take application/json only).
- 422: the body does not match the source's payload schema.
- 429: over 300 events a minute for one source or 1,200 for a workspace, the source is cooling off, or the monthly limit is reached. Honour Retry-After.

## Rules for integrations

- Read the secret from an environment variable such as LITEHOOK_SECRET. Never hardcode, log or commit it.
- Use a timeout of about 5 seconds and never let a failed request to Litehook break the application.
- Keep titles short; put detail in the message. Do not send passwords, keys or personal data.

## Docs

- [Getting set up](https://litehook.app/docs/start): quickstart and phone setup.
- [Sending events](https://litehook.app/docs/sending): endpoints, signed requests, fields, grouping, duplicates, responses.
- [Receiving notifications](https://litehook.app/docs/receiving): device routing, summaries, quiet hours, priority and error sources, the inbox.
- [Building with Litehook](https://litehook.app/docs/build): guided AI prompt and examples for curl, Python, Node.js, Go, Vercel Functions, AWS Lambda, GitHub Actions, GitLab CI, automation builders, Coolify and Home Assistant.
- [Limits](https://litehook.app/docs/limits): rate limits, allowance and cool-off.
- [Security](https://litehook.app/docs/security): how requests are authenticated and how secrets and events are stored.