> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks setup

> Subscribe to Qubrics events, verify signatures, and review delivery attempts.

Webhooks POST events to your HTTPS endpoint when mail is delivered, rejected, bounced, complained about, or received by a mailbox.

> [!NOTE]
>
> New Free teams include **1 webhook**. Your current limit appears on the
> **Webhooks** page. Free limits are fixed. Delete an unused webhook or upgrade
> to Pro when you need more capacity. See [Team limits](https://sendmux.ai/docs/account/team-limits.md).

## Webhooks or realtime events

Use webhooks when your backend should receive signed event POSTs, even while your app is offline. Use the [Mailbox API event stream](https://sendmux.ai/docs/mailbox-api/introduction.md#event-stream) when a mailbox client can keep a live Server-Sent Events connection open and needs immediate received-message updates.

## Create a webhook

**1. Open Webhooks**

Open **Webhooks** in the team workspace and select **Create webhook**.

**2. Enter the endpoint**

Add a name, an HTTPS URL, and the event types you want to receive.

**3. Choose filters**

Keep the webhook team-wide, or scope it to selected mailboxes.

**4. Store the secret**

Copy the signing secret when it appears. It is shown once.

## Process events

Every delivery includes a JSON body and headers that identify the event.

| Header | Use |
| - | - |
| `X-Qubrics-Signature-V2` | Verify the timestamp and exact body bytes. |
| `X-Qubrics-Timestamp` | Check the signed Unix timestamp in seconds. |
| `X-Qubrics-Signature` | Verify the body with the legacy signature. |
| `X-Qubrics-Event-Id` | Dedupe retries for the same event. |
| `X-Qubrics-Event-Type` | Route the event in your application. |
| `X-Qubrics-Delivery-Attempt` | Track retry attempts. |

Verify the signature before acting on an event. See [Verify webhook signatures](https://sendmux.ai/docs/webhooks/verify-signatures.md).

See [Compatibility names](https://sendmux.ai/docs/ai-integrations/mcp#compatibility-names) for retained `SENDMUX_*` settings, webhook headers and MCP tool names.

## Event types

| Event type | When it fires |
| - | - |
| `message.delivered` | A recipient system accepted the message. |
| `message.bounced` | A message bounced. |
| `message.complained` | A recipient marked a message as spam. |
| `message.rejected` | The sending system rejected the message before delivery. |
| `message.delivery_delayed` | Delivery is delayed and still being retried. |
| `message.received` | A mailbox received an inbound message. |
| `message.received.spam` | A mailbox received an inbound message classified as spam. |
| `sendmux.test` | A synthetic event for testing a webhook. |

## Retries

Your endpoint should return `2xx` quickly. Non-`2xx` responses and timeouts are retried across a 24-hour window.

After the final failed attempt, Qubrics marks the webhook as failing and emails the team owner. Fix the endpoint, then disable and re-enable the webhook to resume delivery.

## Review deliveries

Open a webhook to review recent attempts, response status, latency, retry state, and retained payload availability. Delivery metadata and retained payloads are kept for 7 days.

Use **Rotate secret** if a signing secret may have leaked. The new secret is shown once and is used for future deliveries.

Use **Send test** to publish a `sendmux.test` event. Add `sendmux.test` to the webhook event list before testing.

## API access

Use the Management API when you need to create webhooks, list attempts, fetch retained payloads, rotate secrets, or send test events from your own tooling.

> [card] [Management API](https://sendmux.ai/docs/api/introduction.md)
>
> Open the generated Webhooks endpoint reference.

## Related guides

> [card] [Verify signatures](https://sendmux.ai/docs/webhooks/verify-signatures.md)
>
> Check webhook payloads before processing events.

> [card] [Webhook replay](https://sendmux.ai/docs/webhooks/replay.md)
>
> See the coming-soon replay action.

> [card] [Mailboxes](https://sendmux.ai/docs/mailboxes)
>
> Receive inbound mailbox events.

> [card] [Mailbox API events](https://sendmux.ai/docs/mailbox-api/introduction.md#event-stream)
>
> Stream live mailbox events with a mailbox key.

> [card] [Delivery logs](https://sendmux.ai/docs/monitoring/dashboard-logs.md)
>
> Compare webhook events with delivery logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.