---
title: "create webhook subscription"
method: POST
path: "/instances/{id}/webhooks"
tags: ["webhooks"]
---

# create webhook subscription

`POST /instances/{id}/webhooks`

## Request

- Base URL: `https://waapi.app/api/v1`
- URL: `https://waapi.app/api/v1/instances/{id}/webhooks`
- Auth: HTTP bearer

Subscribe a URL to receive instance events. Up to 25 active subscriptions are allowed per instance. Subscribing an already-registered URL again returns the existing subscription with a 200 status instead of creating a duplicate.

## Path parameters

- `id` integer, required

## Headers

- `X-Hook-Secret` string

## Request body

- WebhookSubscriptionCreate
  - `url` string, required: The URL that will receive event payloads.
  - `events` EventType[], required
  - `source` 'zapier' | 'make' | 'n8n' | 'api': Who is registering this subscription. Defaults to api.

## Response `200`

A subscription already existed for this URL — returns it instead of creating a duplicate.

- object
  - `data` WebhookSubscription: A single webhook subscription registered on an instance (as created by Zapier, Make, n8n or a direct API client). Distinct from the instance's own webhook_url/webhook_events, which are set by hand and never expire.
    - `id` integer
    - `url` string
    - `events` EventType[]
    - `source` 'zapier' | 'make' | 'n8n' | 'api'
    - `isActive` boolean
    - `createdAt` string, date-time

## Other responses

- `201`: The created webhook subscription
- `401`: Unauthorized — invalid or missing bearer token
- `403`: Forbidden — insufficient permissions or account blocked
- `404`: Not found — instance does not exist or does not belong to you
- `409`: Conflict — instance is not ready
- `422`: Validation error — invalid or missing request parameters, an unknown event type, or the instance already has the maximum of 25 subscriptions
- `429`: Too many requests — rate limit exceeded

---

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