---
title: "Manage webhooks"
method: POST
path: "/publishers-webhooks"
tags: ["Publish content"]
---

# Manage webhooks

`POST /publishers-webhooks`

## Request

- Base URL: `https://api.opedd.com`
- URL: `https://api.opedd.com/publishers-webhooks`
- Auth: HTTP bearer

`action`:

- `register`: `url` (must be `https://`), `event_types` (one or more of `license.paid`, `license.issued`, `license.revoked`, `license.expired`, `archive.subscribed`), optional `platform` (`canonical` default, `ghost` or `beehiiv`). The answer is the new webhook plus its signing secret `webhook_secret_plaintext` (`whsec_…`), shown once.
- `list`: your webhooks, without secrets.
- `revoke`: `id` of the webhook; revoking twice answers `already_revoked: true`.
- `test`: `id` of the webhook; sends a test event now and tells you whether it arrived (`delivered`, `status_code`).

Each delivery is a `POST` with headers `X-Opedd-Event`, `X-Opedd-Timestamp` (Unix milliseconds), `X-Opedd-Webhook-Id` and `X-Opedd-Signature: sha256=<hex>, t=<timestamp>`. The signature is an HMAC-SHA256, made with your secret, of the raw request body followed directly by the timestamp. Compute the same on your side and compare before trusting a delivery.

Works with your publisher key or your dashboard sign-in. Limits per hour: 10 registrations, 600 lists, 30 removals, 30 tests. `archive.subscribed` can be registered but is not sent at present.

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- union
  - object
    - `action` 'register', required
    - `url` string, uri, required
    - `event_types` string[], required
    - `platform` 'canonical' | 'ghost' | 'beehiiv'
  - object
    - `action` 'list', required
  - object
    - `action` 'revoke', required
    - `id` string, uuid, required
  - object
    - `action` 'test', required
    - `id` string, uuid, required

## Response `200`

Success. The answer depends on `action`.

- object: Every successful response. The endpoint's data is in `data`.
  - `success` true, required
  - `data` union, required
    - object: A webhook you registered.
      - `id` string, uuid
      - `source_id` string, uuid, nullable
      - `platform` 'canonical' | 'ghost' | 'beehiiv': `canonical` unless you set another.
      - `url` string, uri
      - `event_types` string[]
      - `active` boolean
      - `delivery_health` string, nullable
      - `signature_version` string: `v2` for every new webhook (see the endpoint description for how to check it).
      - `created_at` string, date-time
      - `revoked_at` string, date-time, nullable
      - `publisher_id` string, uuid
      - `webhook_secret_plaintext` string: The signing secret (`whsec_…`). Store it now.
      - `warning` string
    - object: Endpoint-specific payload.
      - `webhooks` PublisherWebhook[]
        - `id` string, uuid
        - `source_id` string, uuid, nullable
        - `platform` 'canonical' | 'ghost' | 'beehiiv': `canonical` unless you set another.
        - `url` string, uri
        - `event_types` string[]
        - `active` boolean
        - `delivery_health` string, nullable
        - `signature_version` string: `v2` for every new webhook (see the endpoint description for how to check it).
        - `created_at` string, date-time
        - `revoked_at` string, date-time, nullable
    - object: Endpoint-specific payload.
      - `id` string, uuid
      - `url` string
      - `revoked_at` string, date-time
      - `already_revoked` boolean
    - object: Endpoint-specific payload.
      - `webhook_id` string, uuid
      - `event` object
      - `delivered` boolean
      - `status_code` integer, nullable
      - `delivery_id` string, nullable
      - `reason` string, nullable
  - `request_id` string: Echoed from request `X-Request-Id` header or server-generated.

## Other responses

- `400`: The body failed validation. `error.details` names the fields.
- `401`: Missing or invalid credential
- `404`: `test`: webhook not found
- `429`: Too many requests. Wait for the number of seconds in `Retry-After`, then retry.

---

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