---
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://api.sandbox.alfredpay.io`
- URL: `https://api.sandbox.alfredpay.io/v1/webhook_endpoints`
- Auth: one of:
  - HTTP bearer
  - API key in header `api-key` and API key in header `api-secret`

A prerequisite for every flow, and a step in none of them. Each sequence has at least one point where the next call is only correct after an event arrives.

Store the `secret` when it comes back. Rotation issues a second secret with an overlap window, so nothing is unverifiable mid-rotation.

Delivery, retries, signature verification and what your endpoint must do are all in [Webhooks and events](/docs/webhooks-and-events).

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- object
  - `url` string, uri, required
  - `event_types` string[], required

## Response `201`

Created

- WebhookEndpoint
  - `id` string
  - `url` string, uri
  - `event_types` string[]
  - `secret` string: Returned once, on creation.
  - `status` 'active' | 'disabled'
  - `createdAt` string, date-time

## Other responses

- `400`: Malformed request, so a missing required field, a wrong type or a bad enum.

## Changes

- **2026-11-03** `20fef4fd2ab3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/changes/v1/webhook_endpoints/post.md)

---

[API](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation.md) - [All operations](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/revisions/20fef4fd2ab3?raw)