---
title: "Create a webhook (returns its secret once). Compliance plan"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create a webhook (returns its secret once). Compliance plan

`POST /v1/webhooks`

## Request

- Base URL: `https://api.africacompliancedata.com`
- URL: `https://api.africacompliancedata.com/v1/webhooks`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

At most 3 webhooks per key (409 beyond). The body must be at most 4,000 bytes (413 beyond). The URL must be a public https address on the standard port, without credentials.

## Request body

- object
  - `url` string, uri, required: Public https URL
  - `countries` string[]: ISO codes; empty or omitted = all
  - `features` string[]: Empty or omitted = all. 'vat' includes the VAT rate history, 'wht' the tax treaties.

## Response `200`

Created

- object
  - `id` string
  - `url` string
  - `countries` string[]
  - `features` string[]
  - `created` string, date-time
  - `last_delivery` object, nullable
    - `at` string, date-time
    - `status` union
      - integer
      - string
    - `event` string
  - `secret` string: Signing secret (whsec_...), shown only once
  - `note` string: Reminder to store the secret now

## Other responses

- `400`: Missing or invalid parameter
- `401`: Missing or invalid API key
- `403`: Needs the Compliance plan: finance-law digests and webhooks (or the key is paused for review)
- `409`: 3 webhooks already exist for this key; delete one first
- `413`: Request body over 4,000 bytes
- `429`: Rate limit for the plan exceeded, or key checks busy (many new keys from your network); see Retry-After
- `503`: Key check temporarily unavailable, or webhook storage unavailable (webhook endpoints); retry after Retry-After seconds

---

[API](https://skmtc.dev/africacompliancedata/apis/africa-compliance-data-api.md) · [All operations](https://skmtc.dev/africacompliancedata/apis/africa-compliance-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/africacompliancedata/apis/africa-compliance-data-api/revisions/cb17c8aafda8?raw)