---
title: "Create a webhook endpoint — HMAC-signed deliveries, 0/5/30s retries [write]"
method: POST
path: "/channels/webhooks"
tags: ["channels"]
---

# Create a webhook endpoint — HMAC-signed deliveries, 0/5/30s retries \[write\]

`POST /channels/webhooks`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/channels/webhooks`
- Auth: HTTP bearer

Deliveries carry X-Asteroids-{Event,Delivery,Timestamp,Signature}; ~20 consecutive failures disable the endpoint. Consumers must be idempotent by delivery id. The message.received payload is described by ChannelMessageReceived, including its optional service-owned claim.

## Request body

- CreateChannelWebhook
  - `url` string, required: https (http allowed for localhost only)
  - `events` string[]: Default ["message.received"]

## Response `201`

Created

- ChannelWebhookEndpoint
  - `id` string
  - `url` string
  - `events` string[]
  - `status` string
  - `secret` string: whsec_ HMAC secret — returned on create only

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - added the optional property `error/request_id` to the response with the `default` status

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/channels/webhooks/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)