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

# Create a webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://app.argorant.com`
- URL: `https://app.argorant.com/api/v1/webhooks`
- Auth: HTTP bearer

Argorant calls your HTTPS URL when one of the events happens. The answer holds a signing secret, shown only once: every call carries `X-Argorant-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw body with that secret. Up to 10 webhooks per account, switched off ones included. Campaign events reach the webhooks of the workspace owner and of every active team member; exports, lists and checks reach the person who started them. Included from the Pro plan.

| Cost | What it does | Key scopes |
| --- | --- | --- |
| Free, from the Pro plan | Writes | `argorant:manage_lists` |

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `url` string, uri, required: Your HTTPS endpoint on the public internet.
  - `events` WebhookEvent[], required: Events to receive.

## Response `201`

Created

- object
  - `id` string
  - `url` string
  - `events` string[]
  - `secret` string
  - `note` string

## Other responses

- `400`: 400 Bad request. `invalid_webhook_url` when the address is not a public https:// address; `invalid_request` when an event is unknown, or 10 webhooks exist.
- `401`: 401 Unauthorized. `unauthorized` when the API key is missing, wrong or revoked.
- `402`: 402 Payment required. `plan_required` when webhooks come with the Pro plan.
- `403`: 403 Forbidden. `scope_missing` when the key lacks argorant:manage_lists.
- `409`: 409 Conflict. `idempotency_conflict` when the Idempotency-Key was used with another body.
- `422`: 422 Validation error. `validation_error` when a field has the wrong type or is missing.
- `429`: 429 Too many requests. `rate_limited` when too many requests this minute.

---

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