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

# Register a webhook endpoint

`POST /webhooks/endpoints`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/webhooks/endpoints`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api/docs/webhooks/endpoints/post.ts> (a function with typed inputs; its response is checked against the schema)

Registers an HTTPS endpoint to receive signed events for the caller's organization, subscribed to a set of event types (or all). The signing secret is returned exactly once.

## Request body

- WebhookEndpointCreateRequest: Request body for registering an outbound webhook or BYOS endpoint.
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `config` object: Non-secret configuration for a BYOS destination (e.g. queue_url + region for aws_sqs).
  - `credentials` object: Customer secrets for a BYOS destination (e.g. AWS key/secret). Never stored or logged by Axilio; passed to the delivery gateway, which encrypts them.
  - `event_types` string[], nullable: Event types to subscribe to. Empty means all event types.
  - `type` 'webhook' | 'aws_sqs' | 'aws_s3' | 'aws_kinesis': Destination type: webhook (default when omitted), aws_sqs, aws_s3, or aws_kinesis.
  - `url` string, uri: HTTPS endpoint that signed events are delivered to (webhook destinations).

## Response `201`

Created

- WebhookEndpointCreateResponse: A newly registered webhook endpoint, including its signing secret (shown once).
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `config` object: Non-secret configuration of a BYOS destination (e.g. queue_url + region). Absent for webhook destinations.
  - `created_at` string, date-time, required: Timestamp when the endpoint was registered.
  - `event_types` string[], nullable, required: Subscribed event types ("*" means all).
  - `id` string, required: Endpoint identifier.
  - `secret` string: Standard Webhooks signing secret (whsec_...), webhook destinations only. Shown once at creation and never returned again. Absent for BYOS destinations.
  - `type` 'webhook' | 'aws_sqs' | 'aws_s3' | 'aws_kinesis', required: Destination type: webhook or a BYOS type (aws_sqs, aws_s3, aws_kinesis).
  - `url` string: Delivery endpoint URL (webhook destinations).

## Other responses

- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-23** `49b1da5a7974`: 2 info
  - added the non-success response with the status `422`
  - added the non-success response with the status `500`
- **2026-09-27** `7abfd1e84b24`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api/changes/webhooks/endpoints/post.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api/revisions/80de09d0e643?raw)