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

# Register a webhook endpoint

`POST /v1/webhook-endpoints`

## Request

- Base URL: `https://carbonguru.io`
- URL: `https://carbonguru.io/v1/webhook-endpoints`
- Auth: HTTP bearer

THE SECRET IS IN THIS ANSWER ONLY. Store it when you read it: we hold a verifier for it, not the value, and no route says it again. An endpoint whose secret was lost is rotated. The URL must be https on 443 and must not resolve inside our network; a URL that is not is a 422 invalid_url, and an event we do not fire is a 422 unknown_event. A key may subscribe only to events whose scope it holds. Idempotency-Key applies to the registration and not to the secret: a replay under the same key is a 409 idempotency_secret_not_replayable.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required: An https endpoint on port 443.
  - `events` string[], required: catalog.push.completed, footprint.updated, order.offset, charge.failed, settlement.completed, certificate.issued, analysis.completed, analysis.failed.

## Response `201`

Registered. The secret is stated once, here.

- object
  - `endpoint` WebhookEndpoint, required: One registered webhook endpoint. The signing secret is not part of the resource: it is stated once at registration and once at each rotation, and nowhere else.
    - `id` string
    - `url` string
    - `events` string[]: The events this endpoint subscribes to.
    - `status` string: active or disabled. An endpoint is disabled after repeated delivery failures.
    - `created_at` string, nullable
    - `failure_count` integer, nullable: Consecutive failed deliveries. It resets on a success.
    - `disabled_at` string, nullable
  - `secret` string, required: The signing secret, whsec_… Standard Webhooks signing. It is never returned again.

## Other responses

- `401`: No valid credential. Every authentication failure returns this one document.
- `403`: A missing scope, an exhausted analysis allowance, or an object that is not the caller's.
- `409`: An Idempotency-Key was reused with a different body (idempotency_key_reuse), or a request under the same key is still running (idempotency_in_progress).
- `422`: The request's fields are wrong. errors[] names them.

---

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