Inbound webhooks

Send data to LettrLabs at POST /v1/webhooks/{guid}, with optional HMAC‑SHA256 signature verification and an optional per‑webhook API key.

Inbound webhooks let your systems (or a third party) push data to LettrLabs. You configure a webhook in the LettrLabs app, which gives you a unique endpoint, and your sender posts events to it.

These are inbound webhooks — data flowing into LettrLabs. LettrLabs does not currently emit outbound event webhooks; that is planned for a future release.

Endpoint

Post your payload to the webhook's unique URL:

POST /v1/webhooks/{guid}

{guid} is the identifier of the webhook you created in the app. The full request goes to:

https://app.lettrlabs.com/api/v1/webhooks/{guid}

Security: signature verification and API key

Each webhook can independently require either, both, or neither of two protections, configured per webhook in the app:

Optional HMAC‑SHA256 signature

When signature verification is enabled, the sender computes an HMAC‑SHA256 of the raw request body using the webhook's shared secret and sends it in a standard signature header. The endpoint accepts any of these four headers:

X-Signature-256
X-Hub-Signature-256
X-Signature
X-Hub-Signature

The signature value is the lowercase hex digest, prefixed with sha256=:

X-Signature-256: sha256=3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b

Compute it over the exact raw bytes of the request body (before any parsing). In Node.js:

import { createHmac } from 'node:crypto';

const signature =
  'sha256=' + createHmac('sha256', webhookSecret).update(rawBody).digest('hex');

Send the resulting signature in one of the four accepted headers (for example X-Signature-256). LettrLabs recomputes the digest over the received body and rejects the request if it does not match.

Optional per‑webhook API key

A webhook can also require an API key. When enabled, include your X-API-KEY header on the request (see Authentication & API keys). A webhook may require the API key, the signature, both, or neither — whatever you configured.

Example

curl -X POST https://app.lettrlabs.com/api/v1/webhooks/your-webhook-guid \
  -H "Content-Type: application/json" \
  -H "X-Signature-256: sha256=<computed-digest>" \
  -H "X-API-KEY: your_api_key_here" \
  --data-binary @payload.json

If verification is enabled and the signature header is missing or wrong, or a required API key is absent, the request is rejected.