---
title: "Sendblue Webhook"
method: POST
path: "/api/webhooks/sendblue/{token}"
---

# Sendblue Webhook

`POST /api/webhooks/sendblue/{token}`

## Request

- Base URL: `https://api.yourbeckett.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.yourbeckett.com/api/webhooks/sendblue/{token}`
- Auth: none declared

Inbound Sendblue webhook — receives iMessage events from beta users.

Auth: shared-secret auth is preferred and, when `SENDBLUE_GLOBAL_SECRET`
is configured, is the ONLY accepted mechanism — the legacy tokenized URL
becomes inert (401). The legacy URL-path token on
`/api/webhooks/sendblue/{token}` is only honored when the shared secret is
unconfigured, giving operators a transitional auth path while Sendblue is
rotated to the canonical URL. Shared-secret auth accepts either a direct
secret echo or an HMAC-over-raw-body signature (provider docs / #1523
discovery).

Sendblue returns 5xx-retry on non-2xx; we always return 200 on valid auth
so Sendblue doesn't retry after a processing crash.

Filters:
  1. Shared-secret auth (when configured) OR legacy path-token auth
     (only when shared secret is unset) must verify (401 otherwise)
  2. is_outbound=true → ignore (echo)
  3. message_type != "message" → ignore (call_log, contact_created, etc.)
  4. group_id set → ignore (no group chat support)
  5. status present and != "RECEIVED" → ignore (QUEUED/SENT/DELIVERED)
  6. Duplicate message_handle → ignore (Sendblue retry)
  7. Missing from_number → ignore
  8. Empty content with no media_url → purge Sendblue copy + ignore

On success, spawns `_handle_imessage_inbound` background task and
returns 200 immediately so Sendblue marks the delivery done.

## Path parameters

- `token` string, nullable, required

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/yourbeckett/apis/beckett-platform.md) · [All operations](https://skmtc.dev/yourbeckett/apis/beckett-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/yourbeckett/apis/beckett-platform/revisions/a1cb8f2c8961?raw)