Register Sign in
Docs menu and search Webhooks

Webhooks

Periode can notify your own systems when something happens by sending a webhook — an HTTP POST from Periode’s backend to a URL you control. There are two webhooks:

  • Booking webhook — fires when a booking is completed, and again if it later changes (for example when it is cancelled).
  • Subscription webhook — fires when a subscription is activated, when a following invoice is paid, and when the subscription is cancelled.

Both are configured per product: a webhook is only sent for products where you have filled in a webhook URL.

How a webhook request looks

Every webhook is an HTTP POST with a JSON body. Periode sends these headers:

  • content-type: application/json
  • x-api-key: your merchant shared secret
  • shared_secret: your merchant shared secret, sent as an additional compatibility header

Use the x-api-key header to verify the request really came from Periode — compare it to your shared secret before trusting the payload. You can find your shared secret under Settings > Developer.

Your endpoint should respond with 200 or 201. If it returns anything else, or times out, Periode retries the delivery a number of times (roughly 10 attempts) before giving up, so a temporary outage on your side will not lose the event.

Booking webhook

How it works

When a booking is completed, Periode POSTs the full booking to your URL. The body is the same booking object the Booking API returns, plus a startsAt field with the start of the booking as an ISO timestamp (for example 2026-09-04T13:30:00, in the booking’s own timezone). For active bookings (state booked) the body also includes a cancelUrl. If the booking later changes, Periode sends the booking again with the updated data.

How to enable it

  1. Open the booking product (Booking > Products, then Edit on the product).
  2. Go to the Admin section.
  3. Fill in the Webhook url field with your endpoint.
  4. Save.

From now on, completed bookings for that product are posted to your URL. The webhook is enabled per product — repeat for each product you want to receive.

Subscription webhook

How it works

Periode POSTs the subscription to your URL when the agreement is activated, each time a following invoice is set to paid, and when the agreement is cancelled. The body is the subscription object (the same shape the Merchant API returns for a subscription).

One extra header is included:

  • is-initial: true on the first (activation) webhook for a subscription, false on every webhook after that.

How to enable it

  1. Open the subscription product (Subscription > Products, then Edit on the product).
  2. Go to the API section.
  3. Fill in Webhook for payments (for developers) with your endpoint.
  4. Save.

Testing your webhook

See the exact payload

You do not have to wait for a real event to know what the JSON will look like. In Settings > Integrations, use Preview booking webhook or Preview subscription webhook: enter an existing booking or subscription ID and Periode returns the exact JSON it would send on the webhook. Copy it and build your integration against real data.

Test the whole flow with a free product

To see a live webhook actually reach your endpoint, create a test product with a price of 0 (free). A free product can be booked or subscribed to without a real payment, so you can complete the flow yourself end to end and watch the webhook fire against your URL — without spending anything. Delete or disable the test product when you are done.