---
title: "Create a webhook subscription"
method: POST
path: "/api/external/v2/webhook_subscriptions"
tags: ["Hidden"]
---

# Create a webhook subscription

`POST /api/external/v2/webhook_subscriptions`

Creates a webhook subscription to receive real-time notifications for events occurring within your company or companies.

**Authentication & Scope**
- **Developer Token**: The subscription is scoped to the single company linked to the token.
- **OAuth Application Access Token**: The subscription covers **all companies** accessible by the OAuth application.

**Limits**
Up to 10 webhook subscriptions are allowed per subscriber.

**Secret**
. The secret will be auto-generated.

> 🔒 The secret is **only returned in the creation response** and cannot be retrieved afterwards. Make sure to store it securely.

## Request body

- object
  - `callback_url` string, uri, required — HTTPS URL where webhook events will be sent
  - `events` string[], required — Array of event types to subscribe to. - `customer_invoice.e_invoicing_status_updated`: the event is triggered when a customer invoice e-invoicing status is updated. - `dms_file.created`: the event is triggered when a dms file is created.
  - `enabled` boolean — Indicates whether the webhook subscription is active

## Response `201`

Renders the created webhook subscription

- object
  - `id` integer, required — ID of the webhook subscription
  - `callback_url` string, uri, required — HTTPS URL where webhook events are sent
  - `events` string[], required — Array of event types to subscribe to. - `customer_invoice.e_invoicing_status_updated`: the event is triggered when a customer invoice e-invoicing status is updated. - `dms_file.created`: the event is triggered when a dms file is created.
  - `enabled` boolean, required — Indicates whether the webhook subscription is active
  - `secret` string, required — Automatically generated secret for HMAC signature verification. This is only returned once on creation. Store it securely as it cannot be retrieved afterwards.
  - `created_at` string, date-time, required — Creation date of the webhook subscription
  - `updated_at` string, date-time, required — Last update date of the webhook subscription

## Other responses

- `400` — Bad request
- `401` — Access token is missing or invalid
- `403` — Access to this resource forbidden
- `422` — Unprocessable content

---

[API](https://skmtc.net/pennylane/apis/company-v2.md) · [All operations](https://skmtc.net/pennylane/apis/company-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pennylane/company-v2/revisions/a5b7236473c6/schema)