---
title: "Register an https endpoint"
method: POST
path: "/api/v1/webhooks"
tags: ["Webhooks"]
---

# Register an https endpoint

`POST /api/v1/webhooks`

## Request

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

The URL must be public https; private, loopback and VPN addresses are refused. The secret is returned once. Up to 5 active endpoints per account. Events are sent only for proofs created after registration.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, uri, required
  - `events` string[]: Defaults to proof.polygon.anchored. proof.bitcoin.anchored is a retired name, accepted so old clients are not refused, and never sent (Bitcoin anchoring ended 2026-10-15).

## Response `201`

Registered.

- object
  - `endpoint` WebhookEndpoint
    - `id` integer
    - `url` string, uri
    - `events` string[]
    - `is_active` boolean
    - `created_at` string, date-time
    - `disabled_at` string, date-time, nullable
    - `disabled_reason` string, nullable
    - `last_success_at` string, date-time, nullable
    - `last_failure_at` string, date-time, nullable
    - `failure_streak` integer
  - `secret` string
  - `message` string

## Other responses

- `400`: The request body or parameters were invalid (e.g. hash is not 64-character hex).
- `401`: API key was missing, malformed, or does not match a known key.
- `429`: Rate limit exceeded: 120 requests per minute per API key (fixed window). Retry-After says how many seconds to wait; X-RateLimit-Limit / -Remaining / -Reset are on every keyed response.

---

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