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

# Create a webhook endpoint

`POST /v1/webhooks`

## Request

- Base URL: `https://www.postquick.ai/api`
- URL: `https://www.postquick.ai/api/v1/webhooks`
- Auth: HTTP bearer

Register a URL to receive publish-event webhooks. Returns the plaintext signing secret EXACTLY ONCE — store it immediately. Each delivery has `{ id, event, delivered_at, data }`; `id` matches X-PostQuickAI-Delivery-Id and is stable across automatic retries. Verify the unmodified raw body with X-PostQuickAI-Signature (`t=<unix>,v1=<hex>`; HMAC-SHA256 of `${timestamp}.${rawBody}` using the secret), and reject stale timestamps. Lost secrets can be replaced via /rotate-secret but not retrieved.

## Request body

- object
  - `app_id` string, uuid, required: Content group to attach the endpoint to.
  - `url` string, uri, required: Publicly reachable HTTPS URL. Loopback / private IPs are rejected.
  - `events` string[]: Events to subscribe to. Default is ["*"] (all events). Valid event names: post.{posted,partial,failed}, video.{posted,partial,failed,review_required}, story.{posted,partial,failed}. Subscribe to `video.review_required` (or `*`) to reconcile uncertain video outcomes.

## Response `201`

Endpoint created. Response includes the plaintext signing secret.

- object
  - `success` true, required
  - `data` object, required
    - `endpoint` object, required: A registered webhook endpoint.
      - `id` string, uuid, required
      - `app_id` string, uuid, required
      - `url` string, uri, required
      - `events` string[], required: Subscribed events (e.g. ["post.partial"]) or ["*"] for all.
      - `active` boolean, required
      - `secret_preview` string, required: First 8 chars of the signing secret. Useful for identifying which secret an endpoint uses without exposing it.
      - `consecutive_failures` integer, required: Count of consecutive failed deliveries. Auto-disables the endpoint at 50; resets to 0 on the first 2xx response.
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `secret` string, required: Plaintext signing secret. Returned exactly once.
    - `secret_notice` string, required

---

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