---
title: "Register a webhook for message push delivery"
method: POST
path: "/v1/agent/webhooks"
tags: ["Agent Infrastructure"]
---

# Register a webhook for message push delivery

`POST /v1/agent/webhooks`

HTTPS required (HTTP only for localhost). HMAC-SHA256 signed payloads via X-Voidly-Signature header. Returns webhook secret (shown once).

## Request body

- object
  - `webhook_url` string, uri, required
  - `events` string[]

## Response `201`

Webhook registered. Save the secret for signature verification.

- object
  - `id` string
  - `webhook_url` string
  - `secret` string — HMAC-SHA256 secret (shown once)
  - `events` string[]

## Other responses

- `401` — Invalid or missing X-Agent-Key header

---

[API](https://skmtc.net/voidly/apis/voidly-api.md) · [All operations](https://skmtc.net/voidly/apis/voidly-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voidly/voidly-api/versions/decbe6fd40a8/schema)