---
title: "Create a webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create a webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.sendora.se`
- URL: `https://api.sendora.se/v1/webhooks`
- Auth: HTTP bearer

Registers a URL to receive events. The answer carries the signing secret once; every delivery is signed with it (HMAC-SHA256 over the body) so the receiver can verify Sendora sent it. A second secret can be created later to roll the first one.

## Request body

- object
  - `url` string, required: An https URL on a public host, without credentials or a fragment.
  - `events` string[]: The events to deliver; every event when left out.
  - `streamId` string, uuid: Limits the message events to one stream of the server; every stream when left out. Cap events, on sending and on received mail, concern the server or the account and arrive either way.
  - `inboundContent` 'full' | 'reference': How the inbound event carries a received message: full sends the parsed message with the event; reference sends ids and sizes only, for you to fetch. full when left out.

## Response `201`

The new webhook with its signing secret, shown this once.

- object: The new webhook with its signing secret, shown this once.
  - `webhookId` string, uuid, required
  - `url` string, required: Where the events are posted.
  - `events` string[], required
  - `streamId` string, uuid, nullable, required: The one stream whose message events it receives; null for every stream.
  - `enabled` boolean, required: False while switched off in the dashboard; nothing is queued for it then.
  - `inboundContent` 'full' | 'reference', required: How the inbound event carries a received message: the parsed message, or a reference.
  - `createdAt` string, date-time, required
  - `secrets` object[], required: The live secrets, oldest first; every delivery is signed with each of them, the newest first in Sendora-Signature.
    - `secretId` string, uuid, required
    - `createdAt` string, date-time, required
  - `secret` string, required: The signing secret, shown this once.

## Other responses

- `400`: The body, the query or a header does not match what the route takes.
- `401`: The key is missing, malformed or revoked.
- `403`: The key is of the other kind, or a connected app may not do this here: it is not for connections, the connection may only read here, or it is for test servers only.
- `409`: The server already has a webhook for that URL.
- `422`: The streamId names no stream of this server.

---

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