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

# Register a webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.auxen.ai`
- URL: `https://api.auxen.ai/v1/webhooks`
- Auth: HTTP bearer

Returns the webhook record + a one-time `secret` (HMAC-SHA256 over the raw body, header `x-auxen-signature: sha256=…`). Each delivery includes a unique `delivery_id` for replay protection. Deliveries carry the event name you subscribed with in `event` and the `X-Auxen-Event` header. Pre-2026 event names remain valid until 2027-04-02 (listed as deprecated in the schema); the migration guide maps each to its deployment.* name: https://auxen.ai/docs/api/migration

## Request body

- object
  - `url` string, uri, required
  - `events` union[], required
    - union
      - 'deployment.ready' | 'deployment.error' | 'deployment.deleted' | 'deployment.throughput_changed' | 'deployment.relocated' | 'deployment.suspended' | 'deployment.resumed' | 'deployment.idle' | 'deployment.paused' | 'deployment.warming' | 'deployment.schedule_changed' | 'billing.low_credits' | 'billing.auto_recharge_succeeded' | 'billing.auto_recharge_failed' | 'billing.spending_limit_alert' | 'knowledge_base.indexed' | 'model.update_available'
      - 'instance.ready' | 'instance.error' | 'instance.destroyed' | 'instance.auto_scaled' | 'instance.host_migrated' | 'instance.suspended' | 'instance.resumed' | 'instance.idle' | 'instance.paused' | 'instance.warming' | 'instance.schedule_changed': Pre-2026 event names; accepted until 2027-04-02.
  - `secret` string

## Response `201`

Created

---

[API](https://skmtc.dev/auxen/apis/auxen-headless-api.md) · [All operations](https://skmtc.dev/auxen/apis/auxen-headless-api/llms.txt) · [OpenAPI document](https://skmtc.dev/auxen/apis/auxen-headless-api/revisions/164be65f5ce8?raw)