---
title: "Create Global Webhook Subscription"
method: POST
path: "/webhooks/global/subscriptions"
tags: ["Webhooks"]
---

# Create Global Webhook Subscription

`POST /webhooks/global/subscriptions`

## Request

- Base URL: `https://api.meow.com/v1`
- URL: `https://api.meow.com/v1/webhooks/global/subscriptions`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/meow/apis/meow-api/docs/webhooks/global/subscriptions/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a webhook subscription for every entity your global API key's user administers, including entities added later. New global API keys with business-specific write access cannot use this route. Use the entity-scoped webhook route with x-entity-id for an approved business. Existing global API keys keep their current behavior.

## Headers

- `Idempotency-Key` string, required: A unique key you generate (1-50 printable ASCII characters, no spaces) so retrying this request never creates a duplicate. Reusing a key is rejected.

## Request body

- CreateWebhookSubscriptionRequest
  - `name` string, required: Label for the subscription, for your own reference. Must not be blank.
  - `url` string, uri, required: HTTPS endpoint Meow POSTs each event to.
  - `event_types` WebhookEventType[], nullable: Event types to deliver. Omit or send `null` to receive every event. An empty list is rejected, since it would match nothing.
  - `payload_mode` 'snapshot' | 'thin'

## Response `200`

Successful Response

- WebhookSubscriptionWithSecretResponse
  - `account_id` string, nullable: Bank account whose events this subscription receives. Null means no account filter. Fixed at creation.
  - `id` string, uuid, required: Unique identifier for the subscription.
  - `name` string, required: Label for the subscription.
  - `url` string, required: Endpoint Meow POSTs each event to.
  - `is_enabled` boolean, required: Whether the subscription is currently receiving deliveries. Meow sets this to `false` after repeated delivery failures, a `410 Gone` response, or an unsafe URL; re-enable it with a PATCH.
  - `event_types` WebhookEventType[], nullable, required: Event types this subscription receives. `null` means every event.
  - `payload_mode` 'snapshot' | 'thin', required
  - `created_time` string, date-time, required: When the subscription was created.
  - `updated_time` string, date-time, required: When the subscription was last modified.
  - `secret` string, password, required: Signing secret for verifying delivery signatures. Returned only when the subscription is created and when you rotate the secret — Meow cannot show it again, so store it now.

## Other responses

- `400`: The request could not be processed.
- `401`: Authentication failed.
- `403`: The API key is not authorized for this operation, or the user of a global API key is an admin or controller without approved KYC. The KYC case returns the message `KYC is required for controllers and admins.` until that user completes KYC in the Meow dashboard.
- `429`: Too many requests.

---

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