# Inbound webhooks (/inbound-webhooks)



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.

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

## Endpoint [#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 [#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 [#optional-hmacsha256-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 &#x2A;*`sha256=`**:

```
X-Signature-256: sha256=3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b
```

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

```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 [#optional-perwebhook-api-key]

A webhook can also require an API key. When enabled, include your
&#x2A;*`X-API-KEY`** header on the request (see
[Authentication & API keys](/authentication-api-keys)). A webhook may
require the API key, the signature, both, or neither — whatever you configured.

## Example [#example]

```bash
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.