Webhooks

Beta spec.This page documents the webhook payload and delivery behavior shipping with the launch (webhook channels are a Pro feature). The shape below can still change, so don't build anything irreversible on top of it yet.

The payload

Each new message triggers one HTTP POST to your URL with a Content-Type: application/json body:

{
  "event": "message.created",
  "project": {
    "id": "prj_8f2k1q",
    "name": "acme-site"
  },
  "source": {
    "type": "form",
    "name": "Website contact form"
  },
  "message": {
    "id": "msg_4t9s2e",
    "from": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    "subject": "Question about pricing",
    "body": "Hi, quick question about the Pro plan...",
    "receivedAt": "2026-07-14T09:30:00.000Z"
  }
}

Fields

• event: the event type. message.created is the only event during the beta.
• project: the project whose inbox received the message (its id and name).
• source: where the message came from. type is "form" (the form endpoint) or "email" (the project email address); name is the source's label in your inbox.
• message.from: the sender's email (always present) and name (may be empty when the sender didn't provide one).
• message.subject: optional on form posts, so it may be empty.
• message.receivedAt: ISO 8601 timestamp, UTC.

Delivery

• Respond fast.Return a 2xx status as soon as you've accepted the payload and do any real work asynchronously. Deliveries will time out after 10 seconds.
• At-least-once. A slow response or a transient failure can cause the same message to be delivered more than once. If duplicates matter to your handler, de-duplicate on message.id.

Security

Payloads are not signed yet, which means anyone who discovers your webhook URL can POST a fake payload to it. Until the signing secret ships with the launch:

• Use a long, unguessable path for your webhook URL and don't publish it anywhere.
• Treat every payload as untrusted input: validate it before acting on it.
• Don't trigger destructive or irreversible actions from a beta webhook. Notifying, logging and queuing are fine; deleting things is not.

A signing secret (an HMAC signature header you can verify) is coming with the launch, along with a stable payload spec.

Webhooks vs. notification channels

If all you want is a ping in Discord, Slack or your email when a message arrives, you don't need a webhook. Use a notification channel instead. Webhooks are for feeding messages into your own code, and they're part of the Pro plan (see pricing).