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

# Create a webhook endpoint

`POST /v1/webhooks`

## Request

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

## Request body

- WebhookCreate
  - `url` string, required: Where deliveries go: a public https address
  - `topics` string[], required: The topics to receive
  - `include_pii` boolean: Send contact details (identities, email and phone answers); needs profiles:read, and identity.captured needs it
  - `description` string, nullable: Your own label for the endpoint, at most 200 characters

## Response `200`

The existing endpoint with this URL and configuration, and its secret.

- WebhookCreated
  - `endpoint` WebhookSummary, required
    - `id` string, required: The endpoint
    - `url` string, required: Where deliveries are sent
    - `topics` string[], required: The topics the endpoint receives
    - `status` 'pending' | 'active' | 'disabled' | 'paused_plan', required: pending: waiting for its first successful ping | active | disabled | paused_plan: the store's plan has no API access
    - `include_pii` boolean, required: Whether payloads carry contact details (identities and email and phone answers)
    - `description` string, nullable, required: Your own label for the endpoint; null when unset
    - `created_at` string, date-time, required: When the endpoint was created
    - `updated_at` string, date-time, required: When it last changed
    - `verified_at` string, date-time, nullable, required: When its first ping succeeded; null before
    - `disabled_at` string, date-time, nullable, required: When it was disabled; null while enabled
    - `disabled_reason` string, nullable, required: merchant: you disabled it | gone: it answered 410 | failing_five_days: it kept failing for five days; null while enabled
    - `consecutive_failures` integer, required: Failed deliveries in a row; a success resets it
    - `failing_since` string, date-time, nullable, required: When the current run of failures began; null when the last delivery succeeded
    - `last_delivered_at` string, date-time, nullable, required: When a delivery last succeeded; null before any
  - `secret` string, required: The signing secret (whsec_...); shown only here

## Other responses

- `201`: The new endpoint, pending until a test ping reaches it, and its secret (shown once here).
- `401`: The key is missing, malformed, revoked or expired.
- `403`: The store's plan has no API access, or the key lacks the scope.
- `404`: Not found
- `409`: The endpoint limit was reached or the requested change conflicts with the endpoint's state.
- `422`: A request parameter is invalid.
- `429`: The key's or the store's bucket is full; Retry-After says when to try again.
- `503`: Request limits cannot be checked right now; retry shortly.
- `504`: The request timed out.

---

[API](https://skmtc.dev/octaneai/apis/octane-ai-merchant-api.md) - [All operations](https://skmtc.dev/octaneai/apis/octane-ai-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octaneai/apis/octane-ai-merchant-api/revisions/dc2d1aa2b7c6?raw)