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

# Create a webhook subscription

`POST /api/external/v2/webhook_subscriptions`

## Request

- Base URL: `https://app.pennylane.com`
- URL: `https://app.pennylane.com/api/external/v2/webhook_subscriptions`
- Auth: OAuth 2
  - Authorization code: `https://app.pennylane.com/oauth/authorize`
  - Token URL: `https://app.pennylane.com/oauth/oauth/token`

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

**Authentication & Scope**

Subscription scope:
- **Company-scoped token** (developer token or OAuth token bound to a specific company): the subscription is scoped to that single company.
- **App-bound token** (OAuth token without a company context): the subscription covers all companies accessible by the OAuth application.

**Limits**
Up to 10 webhook subscriptions are allowed per company (for company-scoped tokens) or per subscriber (for app-bound tokens).

**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. - `supplier_invoice.e_invoicing_received`: the event is triggered when a supplier e-invoice is received via the Pennylane PA (Plateforme Agrée).
  - `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. - `supplier_invoice.e_invoicing_received`: the event is triggered when a supplier e-invoice is received via the Pennylane PA (Plateforme Agrée).
  - `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

## Changes

- **2026-11-03** `871f863307e5`: 1 warning, 3 info
  - added the new `supplier_invoice.e_invoicing_received` enum value to the `events/items/` response property for the response status `201`
  - api tag `Webhooks` added
  - api tag `Hidden` removed
  - added the new `supplier_invoice.e_invoicing_received` enum value to the request property `events/items/`

[Operation history](https://skmtc.dev/pennylane/apis/company-v2/changes/api/external/v2/webhook_subscriptions/post.md)

---

[API](https://skmtc.dev/pennylane/apis/company-v2.md) - [All operations](https://skmtc.dev/pennylane/apis/company-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/pennylane/apis/company-v2/revisions/871f863307e5?raw)