Skip to content

Paddle webhook

POST
/v1/billing/webhooks/paddle
curl --request POST \
--url https://beta-api.plune.ai/v1/billing/webhooks/paddle \
--header 'Content-Type: application/json' \
--header 'Paddle-Signature: example' \
--data '{ "event_id": "evt_01hv8x2a", "event_type": "subscription.created", "occurred_at": "2026-11-13T10:00:00.000Z", "notification_id": "ntf_01hv8x2b", "data": { "id": "sub_01hv8x2c", "status": "active", "custom_data": { "payment_subscription_id": "00000000-0000-4000-8000-000000000000" } } }'

Called by Paddle, not by a person or a CI. No session and no token: Paddle-Signature is ts=<unix>;h1=<hex>: HMAC-SHA256 of ts: + the raw body with the notification destination’s secret, within 5 seconds; any of several h1 may match, checked on the raw bytes of the body before any JSON is read. A verified event is stored once (provider + its own key) and applied to the tier by the worker; a repeat delivery answers 200 and changes nothing. While PADDLE_WEBHOOK_SECRET is unset on the server the route answers 503 provider_not_configured and stores nothing. The body is held to 512 KiB.

Paddle-Signature
required
string

ts=<unix>;h1=<hex>: HMAC-SHA256 of ts: + the raw body with the notification destination’s secret, within 5 seconds; any of several h1 may match

Media type application/json
object
Example
{
"event_id": "evt_01hv8x2a",
"event_type": "subscription.created",
"occurred_at": "2026-11-13T10:00:00.000Z",
"notification_id": "ntf_01hv8x2b",
"data": {
"id": "sub_01hv8x2c",
"status": "active",
"custom_data": {
"payment_subscription_id": "00000000-0000-4000-8000-000000000000"
}
}
}

The event is stored (stored), or the same delivery was already (duplicate). Sent only after the write committed.

Media type application/json
object
outcome
required
string
Allowed values: stored duplicate
Example
{
"outcome": "stored"
}

The signature is right but the body is not an event of this provider

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

The signature is missing or does not match; the body is empty

The body is over 512 KiB

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

PADDLE_WEBHOOK_SECRET is not set on this server (code: provider_not_configured)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}