---
title: "Create a webhook subscription"
method: POST
path: "/accounts/integrations/{id}/subscriptions"
tags: ["Task Subscriptions"]
---

# Create a webhook subscription

`POST /accounts/integrations/{id}/subscriptions`

## Request

- Base URL: `https://api.quiva.ai`
- URL: `https://api.quiva.ai/accounts/integrations/{id}/subscriptions`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/docs/accounts/integrations/:id/subscriptions/post.ts> (a function with typed inputs; its response is checked against the schema)

Up to 25 per integration. `400 bad_url`, `400 space_not_in_scope`, `409 subscription_limit`, `409 integration_disabled`.

## Path parameters

- `id` string, required

## Request body

- CreateSubscriptionRequest
  - `url` string, uri, required: https only. Private, loopback and link-local hosts are refused.
  - `spaces` string[], required: Each space needs `tasks:read` on the integration.
  - `event_kinds` string[]

## Response `200`

Created.

- object
  - `data` SubscriptionCreated, required
    - `subscription` TaskSubscription, required
      - `id` string, required
      - `account_id` string, required
      - `integration_id` string, required
      - `spaces` string[], required
      - `event_kinds` string[], required: Empty means all kinds.
      - `url` string, uri, required
      - `previous_secret_until` string, date-time: While in the future, deliveries carry a second signature from the previous secret.
      - `environment` string
      - `paused` boolean, required
      - `paused_reason` '' | 'endpoint_gone' | 'consecutive_failures' | 'failing_for_24h' | 'integration_disabled' | 'scope_removed'
      - `paused_at` string
      - `consecutive_failures` integer
      - `failing_since` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `secret` string, required: `whsec_` + base64 of 32 bytes. Shown once.

## Other responses

- `400`: Bad request. `code` names the cause.
- `401`: Not authenticated, the caller is not a root or admin user, or the integration token was revoked (`token_revoked`).
- `403`: Forbidden: `scope_denied`, or `integration_not_allowed` for an integration bearer outside workspaces.
- `404`: Not found.
- `409`: Conflict. `code` names the cause.
- `503`: A backing store is unreachable. Retry. `code` is `storage_unavailable`.

## Changes

- **2026-10-08** `bcf3a5f49584`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/changes/accounts/integrations/:id/subscriptions/post.md)

---

[API](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway.md) - [All operations](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/revisions/700eb1ace61a?raw)