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

# Create a webhook endpoint

`POST /webhooks`

## Request

- Base URL: `https://api.rizamo.com/v1`
- URL: `https://api.rizamo.com/v1/webhooks`
- Auth: HTTP bearer

Events from now on go to it, of the profiles the person it sends for reaches (`onBehalfOf`: the caller, or the person behind the API key or agent), and it is deleted when they leave the team. Each event goes as one POST of JSON (the event as `List events` gives it), signed with Standard Webhooks' headers (`webhook-id`, the event's id; `webhook-timestamp`; `webhook-signature`). A 2xx answer within 15 seconds is delivered; anything else is tried again 6 times over about 18 hours, and a 410 Gone disables the endpoint. After 10 failures in a row an endpoint's deliveries wait while one at a time tries it, and one that keeps failing like that with nothing delivered for 5 days is disabled; Rizamo emails the team's owners and the person it sends for. Never sent to rizamo.com or workers.dev addresses, nor to private ones. Deliveries are not in order: order one resource's events by `at`. Its signing secret is in the answer, and only there. A team has up to 20 endpoints.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required: Where Rizamo sends events: an https address on the public internet.
  - `description` string: What it is for, for the people of the team.
  - `events` WebhookEventType[], nullable: The event types it receives. Null: every type, those Rizamo adds later included. A key or agent lists the inbox's types (`comment.received`, `message.received`, `message.sent`) only with `inbox:read`, and `comment_automation.*` only with `automations:read`; with null, the endpoint gets none of those it cannot read.
  - `profileIds` string[], nullable: Only events of these profiles. Null: every profile's, and the events of no profile. Someone limited to some profiles gives some of theirs.

## Response `201`

OK

- WebhookSecret
  - `endpoint` WebhookEndpoint, required
    - `id` string, required
    - `url` string, uri, required
    - `description` string, required
    - `events` WebhookEventType[], nullable, required: The event types it receives. Null: every type, those Rizamo adds later included. The inbox's (`comment.received`, `message.received`, `message.sent`) and comment automations' (`comment_automation.*`) carry what people wrote: an endpoint a key or agent made, or last pointed at its `url`, gets them only if it had `inbox:read` (`automations:read` for automations), whatever this lists.
    - `profileIds` string[], nullable, required: Only events of these profiles, and of those only the ones its person reaches now (`onBehalfOf`). Null: every profile's, and the events of no profile. Empty once every profile it was limited to is deleted: it is then disabled. Someone limited to some profiles only sees and makes endpoints within them.
    - `status` 'active' | 'failing' | 'disabled', required: active: sends, and its last attempt was delivered (or none was made yet). failing: sends, but its last attempt failed; after 10 failures in a row its deliveries wait while one at a time tries it (`breaker`). disabled: sends nothing, see `disabledReason`.
    - `disabledReason` 'by_request' | 'gone' | 'failing' | 'profile_deleted', nullable, required: by_request: someone set `enabled` to false. gone: the endpoint answered 410 Gone. failing: its breaker was open and nothing got through for 5 days; for these two Rizamo emails the team's owners and editors. profile_deleted: every profile it was limited to was deleted, which leaves `profileIds` empty; give it profiles to enable it again. Null while it sends.
    - `breaker` 'closed' | 'open', required: open: it failed 10 times in a row, so its deliveries wait and one at a time tries it every 15 minutes; the first one delivered, or a test that gets through, sends the rest. closed: deliveries go as they come. A new `url` starts closed.
    - `failingSince` string, date-time, nullable, required: Its first failed attempt of the failures in a row (failures hours apart, further than the retries' spacing, start anew). Null once an attempt is delivered.
    - `disablesAt` string, date-time, nullable, required: When Rizamo disables it unless an attempt is delivered first: `failingSince` and 5 days, while its breaker is open. Null otherwise.
    - `successRate` number, nullable, required: Of the attempts in the last 7 days, the percent delivered (a 2xx answer). Null with none.
    - `lastDeliveryAt` string, date-time, nullable, required: When Rizamo last tried to deliver to it, whatever the answer.
    - `createdBy` union, required
      - object
        - `type` 'agent', required
        - `agent` 'claude' | 'chatgpt' | 'claudecode' | 'cursor' | 'codex' | 'gemini' | 'perplexity' | 'openclaw' | 'n8n' | 'make' | 'zapier', nullable, required
        - `name` string, required
        - `agentId` string
        - `onBehalfOf` object: The person whose agent it is, who connected it and whom it acts as, with their role: "Ana via Claude Code". Events from before 2026-11-02 have it too, with the person's name now. Left out of an agent with no person, and of other records from before. After the person's erasure, `name` is "A former member" and `userId` empty.
          - `userId` string, required
          - `name` string, required
      - object
        - `type` 'user', required
        - `userId` string, required
        - `name` string, required
        - `initials` string, required
      - object
        - `type` 'api_key', required
        - `keyId` string, required
        - `name` string, required
      - object
        - `type` 'automation', required
        - `automationId` string, required
        - `name` string, required
    - `onBehalfOf` object, nullable, required: The person it sends for: whoever made it or last pointed it at its `url`, or the person behind the API key or agent that did. It sends only events of the profiles they reach now (events of no profile only while they reach every profile), owners and they alone see and manage it, and it is deleted when they leave the team. Null once they are no longer on the team: it sends nothing until an owner changes it, which makes them its person.
      - `userId` string, required
      - `name` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `secret` string, required: The signing secret (`whsec_` and base64), shown only now: keep it where your receiver reads it. Each delivery's `webhook-signature` is `v1,` and the base64 HMAC-SHA256, keyed with the base64 after `whsec_`, of `<webhook-id>.<webhook-timestamp>.<body>`.

## Other responses

- `400`: `invalid_request`: A field is missing or wrong, or the request cannot be done as asked: the message names the field or says what to change.
- `401`: `unauthorized`: No API key or sign-in, or the key does not work: it was deleted, or it expired.
- `403`: `forbidden`: The caller may not do this: the key or agent lacks the scope (the message names it), or the action needs another role or a fresh sign-in.
- `409`: `conflict`: The object's state does not allow it now, such as an account that needs a new login. `queue_empty`: A post with `queue: true` whose profile has no posting times: set them, or give a `scheduledAt`. `queue_full`: No posting time free for the post's accounts in the next 90 days: add times, or give a `scheduledAt`. `idempotency_key_in_use`: A request with this `Idempotency-Key` is still running: try again in a moment.
- `413`: `payload_too_large`: The body is over 1 MB: files go up through the upload links of `POST /v1/media`.
- `415`: `unsupported_media_type`: The body is not JSON: send it with `Content-Type: application/json`.
- `422`: `capability_missing`: The account cannot do this: see its `capabilities`. `idempotency_key_reused`: This `Idempotency-Key` was used for a different request in the last 24 hours: send a new key.
- `429`: `rate_limited`: Over one of Rizamo's limits, or a network asked Rizamo to slow down: wait for `Retry-After` seconds, or as long as the message says.
- `500`: `internal`: Our side failed: retry, and send the `requestId` if it keeps failing.
- `503`: `timeout`: The request took too long to work out, most often a report: try again in a moment, or ask a report for a shorter period or one profile.

---

[API](https://skmtc.dev/rizamo/apis/rizamo-api.md) - [All operations](https://skmtc.dev/rizamo/apis/rizamo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rizamo/apis/rizamo-api/revisions/31b0c1b1ffb5?raw)
