events.mdx.vel

---
title: Webhook events
description: Headers and JSON fields delivered for inbound messaging events
---

Spectrum currently emits one webhook event type: `message.received`. It carries
the inbound provider request in a stable JSON envelope.

## Example delivery

```http
POST /spectrum-webhook HTTP/1.1
Content-Type: application/json
webhook-id: 0198f123-4567-7000-8000-123456789abc
webhook-timestamp: 1785788130
webhook-signature: v1,SGVsbG8...

{
  "type": "message.received",
  "timestamp": "2026-08-03T20:15:30.123Z",
  "schemaVersion": 1,
  "eventId": "0198f123-4567-7000-8000-123456789abc",
  "projectId": "2c8f1234-5678-4000-8000-123456789abc",
  "platform": "whatsapp",
  "receivedAt": "2026-08-03T20:15:30.123Z",
  "sourceId": "provider-request-123",
  "prevSubjectSeq": 41,
  "request": {
    "method": "POST",
    "path": "/events",
    "headers": {
      "content-type": "application/json",
      "user-agent": "provider-webhook/1.0"
    },
    "bodyEncoding": "json",
    "body": {
      "message": "hello"
    },
    "rawBodyBase64": "eyJtZXNzYWdlIjoiaGVsbG8ifQ=="
  }
}
```

Spectrum uses the Standard Webhooks convention that data fields may be
squashed into the top-level object. There is no additional `data` wrapper.

Selecting `schemaVersion: "raw-inbound.v1"` when you register an endpoint pins
this payload contract. The numeric `schemaVersion` inside the delivered JSON is
the revision of this raw inbound envelope.

## Standard Webhooks headers

| Header | Description |
| --- | --- |
| `Content-Type` | `application/json`. |
| `webhook-id` | Stable id for the logical event. It equals `eventId` in the body. |
| `webhook-timestamp` | UNIX epoch seconds at signing time. |
| `webhook-signature` | One or more space-delimited `v1,<base64>` signatures. |

The event id never contains a period, so the Standard Webhooks signed-content
serialization remains unambiguous. The same event keeps its id across retries
and multiple endpoints.

See [Verifying signatures](/webhooks/verifying-signatures) before processing a
delivery.

## Payload fields

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"message.received"` | Subscription and routing discriminator. |
| `timestamp` | RFC 3339 string | When Spectrum received the source request. |
| `schemaVersion` | `1` | Version of this JSON envelope. |
| `eventId` | string | Stable logical event id; same value as `webhook-id`. |
| `projectId` | UUID | Spectrum project that owns the event. |
| `platform` | string | Source provider, such as `imessage` or `whatsapp`. Treat new values as forward-compatible. |
| `receivedAt` | RFC 3339 string | Source-ingress receipt time. Normally the same as `timestamp`. |
| `sourceId` | string, optional | Provider or ingress source identifier when available. |
| `prevSubjectSeq` | integer | Previous sequence observed for the source subject; `0` means none was recorded. |
| `request` | object | Normalized representation of the original inbound HTTP request. |

Consumers should ignore unknown fields so Spectrum can add optional metadata
without breaking existing handlers.

## Request fields

| Field | Type | Description |
| --- | --- | --- |
| `method` | string | Original HTTP method. |
| `path` | string | Original request target, including its query string when present. |
| `headers` | object | Original headers with lowercase names. Repeated values are comma-joined. |
| `bodyEncoding` | `json`, `form`, `text`, or `base64` | How `body` was decoded. |
| `body` | JSON, object, or string | Convenient decoded representation. |
| `rawBodyBase64` | string | Original request-body bytes encoded as Base64. |

`bodyEncoding` is selected as follows:

| Source body | `bodyEncoding` | `body` value |
| --- | --- | --- |
| Valid `application/json` or `*+json` UTF-8 | `json` | Parsed JSON value. |
| `application/x-www-form-urlencoded` UTF-8 | `form` | Object; repeated keys become arrays. |
| Other valid UTF-8, including malformed JSON | `text` | Original text. |
| Non-UTF-8 bytes | `base64` | Base64 string. |

`rawBodyBase64` is always present, including when `body` has already been
decoded. Use it when byte-for-byte source fidelity matters.

<Warning>
The request envelope can contain provider message content and original headers.
Treat webhook payloads as sensitive data: require HTTPS, verify signatures, and
avoid logging the complete body or header map.
</Warning>

## Compatibility headers

Fusor also sends additive transport metadata:

| Header | Purpose |
| --- | --- |
| `idempotency-key`, `x-fusor-event-id` | Same event id as `webhook-id`. |
| `x-fusor-project-id` | Project id. |
| `x-fusor-source` | Source platform. |
| `ce-*` | CloudEvents 1.0 binary-mode context for delivery observability. |
| `X-Spectrum-Event` | Legacy event label, currently `messages`. |
| `X-Spectrum-Webhook-Id` | Endpoint registration id. |
| `X-Spectrum-Timestamp` | Legacy signing timestamp. |
| `X-Spectrum-Signature` | Legacy `v0=<hex>` signature. |

The Standard and legacy signatures cover the same exact JSON body. New
integrations should route with `type`, deduplicate with `webhook-id`, and verify
`webhook-signature`.

## Event subscriptions

Set an endpoint's `eventTypes` to the events it should receive. The only
currently accepted value is:

```json
{
  "eventTypes": ["message.received"]
}
```

Spectrum filters before publishing endpoint delivery work. Additional event
types can therefore be introduced without sending them to endpoints that did
not subscribe.