---
title: "Add a webhook endpoint; the response carries its signing secret, once"
method: POST
path: "/api/webhooks"
---

# Add a webhook endpoint; the response carries its signing secret, once

`POST /api/webhooks`

## Request

- Base URL: `https://postwire.io`
- URL: `https://postwire.io/api/webhooks`
- Auth: HTTP bearer

## Request body

- object
  - `url` string, uri, required: A public https URL. Redirects are not followed.
  - `events` string[]: Default: post.published, post.failed and connection.reauth_required. approval.requested and approval.decided are sent only to an endpoint that lists them.
  - `description` string

## Response `201`

{ webhook: Webhook, secret: "whsec_…" } — keep the secret: it is not shown again

## Other responses

- `400`: code bad_url (not https, not public, malformed), bad_request (unknown event) or too_many (your plan's endpoints are all in use; the body carries limit, your plan's number)
- `503`: code webhooks_unavailable

---

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