/v1/subscriptions

Create a subscription that delivers chosen events to your endpoint.

Registers an HTTPS endpoint to receive signed event payloads. The response includes the subscription's signing secret — store it, because it is only returned once. Deliveries begin with the next matching event.

Jump to the request builder ↓

Parameters

Body parameters

url string required

HTTPS endpoint that receives signed event payloads. Must respond with a 2xx within 10 seconds.

Example: https://example.com/hooks/hooklane
events array of strings required

Event types to deliver, as a comma-separated list. Use * to subscribe to every event.

Example: invoice.paid, invoice.payment_failed
description string optional

Internal label shown in the dashboard and the delivery log.

Example: Production billing endpoint
active boolean optional

Set to false to create the subscription paused; no deliveries are attempted until it is activated.

Example: true

Response

The new subscription. `secret` is the signing key for the `X-Hooklane-Signature` header and is only included in this response.

200 · application/json

{
  "id": "sub_9f2c1a",
  "object": "subscription",
  "url": "https://example.com/hooks/hooklane",
  "events": [
    "invoice.paid",
    "invoice.payment_failed"
  ],
  "description": "Production billing endpoint",
  "active": true,
  "secret": "whsec_Zr8kP2mQ4tVxCn6b",
  "created_at": "2026-08-28T09:12:44Z"
}