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

# Create a webhook endpoint

`POST /v1/webhooks/endpoints`

## Request

- Base URL: `https://api.0xarchive.io`
- URL: `https://api.0xarchive.io/v1/webhooks/endpoints`
- Auth: API key in header `X-API-Key`

Register an HTTPS destination and get its signing secret. The secret is returned in this response and in a rotation, and nowhere else, so store it now. Destinations that resolve to a private or internal address are refused, at creation and again on every delivery. A plan without webhook delivery, or one already at its endpoint cap, is refused with the reason and the way forward. Authenticate with an API key or a signed-in dashboard session. Costs no credits. Deliveries are signed with the secret in the `0xa-signature` header (see the `delivery` callback).

## Request body

- WebhookEndpointCreateRequest: A new delivery destination.
  - `url` string, uri, required: HTTPS destination that will receive deliveries. Destinations that resolve to a private or internal address are refused.
  - `description` string: Your own label for the endpoint.
  - `format` 'json' | 'discord' | 'slack': Delivery format. Omit it to detect from the URL: a Discord webhook URL becomes `discord`, a Slack incoming-webhook URL becomes `slack`, anything else `json`. Case-insensitive. Telegram endpoints are created by connecting a chat, not here.

## Response `200`

The new endpoint and its signing secret

- ApiResponseWebhookEndpointCreated: API response containing a newly created endpoint and its signing secret.
  - `success` boolean
  - `data` WebhookEndpointCreated: A newly created endpoint, including the signing secret. This is one of the two responses that carry the secret; the other is a rotation. Store it now, because it is not shown again.
    - `id` string, uuid, required: Endpoint identifier.
    - `url` string, uri, required: HTTPS destination that receives deliveries.
    - `description` string, required: Your own label for the endpoint.
    - `format` 'json' | 'discord' | 'slack' | 'telegram', required: How deliveries are rendered. `json`: the signed JSON envelope (`WebhookDeliveryEnvelope`). `discord` and `slack`: a chat message in that service's webhook format, still signed. `telegram`: a message posted to a connected Telegram chat; Telegram endpoints are created by connecting a chat, not by URL, and their deliveries carry no signature.
    - `status` 'active' | 'disabled' | 'auto_disabled', required: `active` is serving. `auto_disabled` means a long run of failed deliveries switched it off; bring it back with the enable route, which also resets the failure count. `disabled` is reserved.
    - `consecutive_failures` integer, required: Failed attempts since the last success. Resets to zero on a delivery that lands.
    - `created_at` string, date-time, required: When the endpoint was created.
    - `secret` string, required: Signing secret for this endpoint. Every delivery is signed with it, and your receiver verifies the signature against it.
  - `note` string: That the secret is shown once.

## Other responses

- `400`: Invalid request: a parameter, symbol, interval, cursor or time range failed validation. See `error_code`.
- `401`: Authentication required: the API key is missing or invalid.
- `429`: Rate limit, concurrency limit or monthly credits exceeded. See `error_code`.
- `default`: Any other error. The body is an `ErrorResponse`; branch on `error_code`. A 503 (`upstream_unavailable`) carries `Retry-After`.

---

[API](https://skmtc.dev/0xarchive/apis/0xarchive-api-2.md) · [All operations](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/revisions/27076f55595f?raw)