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

# Add a webhook

`POST /webhooks`

## Request

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

An https address on the public internet and the events to send it. The answer carries the signing secret, this once. Each delivery is a POST of `{ id, type, created_at, data }` with `Pagefully-Signature: t=<unix seconds>,v1=<hex>`, where v1 is HMAC-SHA256 with the secret over the timestamp, a full stop and the body as sent. Refuse one more than 300 seconds old, and dedupe by `id`: a delivery is made at least once. Anything but a 2xx is tried again, 6 attempts in all, after 60, 300, 1800, 7200, 43200 seconds. No redirect is followed. An address on a private or local network is refused. A workspace holds 5. There is no page.live and no page.rejected. Pagefully makes a page in App Store Connect and does not submit it for review, and it does not read Apple's verdict back, so it cannot say that a page went live or was rejected.

## Request body

- object
  - `url` string, uri, required: https only.
  - `events` string[], required

## Response `201`

Added. `secret` is shown this once.

- object
  - `webhook` Webhook, required
    - `id` string, uuid, required
    - `url` string, required
    - `events` string[], required
    - `created_at` string, required
    - `last_delivery` object, nullable, required
      - `event` string, required
      - `status` 'pending' | 'sending' | 'delivered' | 'failed', required
      - `response_code` integer, nullable, required
      - `error` string, nullable, required
      - `attempt` integer, required
      - `at` string, required
      - `said` string, required
  - `secret` string, required: whsec_ and 32 characters.
  - `next` string, required

## Other responses

- `400`: The request could not be read: a body that is not a JSON object, or a field missing or of the wrong kind.
- `401`: No token, or one that is not valid or has been revoked.
- `403`: The token's scope does not allow this call.
- `422`: Understood, and refused by the product. The message says why, in a sentence that can be shown as it is.
- `429`: Too many calls: 120 requests a minute for a token, and 20 generation starts an hour. `retry_after` is seconds.

---

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