---
title: "Event delivered to your webhook URL"
method: POST
path: "mailboxEvent"
tags: ["webhooks"]
---

# Event delivered to your webhook URL

`POST mailboxEvent` (webhook)

Verify `Botmail-Signature` before trusting the body:
`hex(HMAC-SHA256(secret, t + "." + raw_body)) == v1`. Respond 2xx
within 10 seconds; anything else is retried (5 s doubling, max 1 h).
De-duplicate on `Botmail-Event-Id`.

## Headers

- `Botmail-Signature` string, required
- `Botmail-Event-Id` string, required

## Payload

- WebhookEvent
  - `id` string, required: `evt_<seq>`; same as the Botmail-Event-Id header.
  - `type` 'message.received' | 'message.sent' | 'message.status' | 'thread.updated' | 'mailbox.claimed', required
  - `mailbox_id` string, required
  - `thread_id` string, nullable
  - `message_id` string, nullable
  - `created_at` string, date-time, required
  - `data` object, required

## Acknowledgement `2XX`

Accepted. Any 2xx marks the event delivered.

## Other responses

- `default`: Treated as a failure and retried.

---

[API](https://skmtc.dev/botmail/apis/botmail-api.md) · [All operations](https://skmtc.dev/botmail/apis/botmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/botmail/apis/botmail-api/revisions/49f736362bf2?raw)