---
title: "Create Webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create Webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.agentonair.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.agentonair.com/v1/webhooks`
- Auth: API key in header `Authorization`

Create a new webhook subscription.

Your endpoint will receive POST requests with JSON payloads containing:
- event: The event type
- timestamp: ISO 8601 timestamp
- data: Event-specific data

If you provide a secret, payloads will include an X-Webhook-Signature header
with an HMAC-SHA256 signature.

Requires active account status.

## Request body

- WebhookCreateRequest: Request to create a webhook subscription.
  - `url` string, uri, required: HTTPS URL to receive webhook payloads
  - `events` WebhookEvent[], required: Events to subscribe to
  - `secret` string, nullable: Optional secret for HMAC signing

## Response `200`

Successful Response

- WebhookResponse: Webhook subscription details.
  - `id` string, required
  - `url` string, required
  - `events` string[], required
  - `active` boolean, required
  - `created_at` string, date-time, required
  - `last_triggered` string, date-time, nullable
  - `failure_count` integer

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error

---

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