A webhook is a simple mechanism that allows PPRO to push event-driven messages using HTTP POST calls to an endpoint that you define, they are crucial for keeping your systems synchronized with the latest status of the entities. Webhooks are an essential feature of a successful integration with PPRO.

This request contains a JSON payload describing the event and the associated resource. You need to accept webhooks that you receive with a 2xx HTTP status code, store the message, and process the contents of the message.

Webhooks remove the need to continuously poll an API endpoint for status updates in asynchronous processes. They are particularly useful for long-running operations, where changes to a resource or its status may occur after seconds, minutes, hours, or even days. Instead, you can initiate an API request and continue with other tasks. When a relevant event occurs, PPRO notifies you via a webhook, allowing you to respond to the status change as needed.

For maximum compatibility and ease of integration with your cloud infrastructure, all PPRO webhooks follow the CloudEvents 1.0.2 specification. This provides a consistent, standardized envelope for all event data, regardless of the event type.

Endpoint requirements

Before you can receive webhooks, you must configure a dedicated endpoint on your server. This endpoint acts as a callback URL for PPRO.


HTTPS only	Your endpoint must be secured with HTTPS and configured to listen for incoming requests on an open TCP port for HTTPS traffic (on port 443). Note - If you require webhook delivery on a non-standard port (i.e. other than 443), please contact your PPRO Account Manager to request enablement.
Set the URL	Specify your endpoint URL using the `webhooksUrl` parameter in your initial API requests (e.g., when creating a payment charge or payment agreement). Alternatively, you can ask your PPRO Account Manager to set a default `webhooksUrl` configuration for your account. Note - If required separate URLs can be configured for payments and dispute events.
Custom headers	You can optionally configure static custom headers (fixed key-value pairs) in the webhook configuration if your endpoint requires them for internal routing, authentication, or additional security.
Signing secret	To protect your server from unauthorized webhooks, we strongly recommend using Hash-based Message Authentication Code (HMAC) signatures which are provided in the `PPRO-Signature` header. By verifying the signature included in each webhook event, you can ensure that the event originated from PPRO and has not been altered in transit. Please contact your PPRO Account Manager to set the secret for your account. Note - The support for the non-HMAC `Webhook-Signature` headers is deprecated for new customers.

Responding to webhooks

To ensure reliable delivery and avoid unnecessary retries, your endpoint must respond quickly and correctly. Do this before executing any complex business logic:

Acknowledge immediately: Your server must return an HTTP 2xx response code (e.g., 200 OK) as soon as possible after receiving the request. This signal confirms receipt to PPRO.
Store first: Immediately store the webhook payload in your database. Defer the actual processing (updating inventory, sending customer emails, etc.) to a background job queue. This practice prevents timeouts and ensures you don't lose events.

Retrying webhooks

If PPRO does not receive a successful acknowledgement (an HTTP 2xx response), we automatically retry the delivery to ensure you don't miss a critical event.

We use an exponential backoff model for retries:

First retry: Occurs after 15 seconds.
Subsequent attempts: The interval is doubled for each subsequent attempt.
Maximum: The system attempts a maximum of 15 deliveries.
Total window: The total retry window for a single webhook event spans approximately 68 hours.

Verifying webhooks

To ensure that a webhook truly originates from PPRO and has not been altered in transit, we strongly recommend that you validate the signature included in the respective headers.

How to verify HMAC signatures

ppro-signature: t=1776785532,s=5271af077eb3525e5c50ceaa44834ff10cc6f32f6bd060e341e0dad60bae49bb

Compute a hash using the following formula:

sha256(t + "." + payload)

t is the UNIX timestamp from the PPRO-Signature header.
payload is the raw content string payload in the webhook body (NOT in prettified JSON format).
Use the pre-configured secret as the HMAC signing key.
It is best advised to validate the timestamp to know if the webhook is recent enough as it is also used to calculate the SHA.

Compare your computed HMAC hash with the s value from the PPRO-Signature header.

How to verify Custom signatures (deprecated)

webhook-signature: fccb970608324c31c8f1bdf2cd6af76b9b28733a08f297bd9e693bd813aec041

Compute a hash using the following formula:

sha256(payload + "." + signingSecret)

signingSecret is the secret key that is pre-configured.
payload is the raw content string payload in the webhook body (NOT in prettified JSON format).

Compare your computed hash with the value from the Webhook-Signature header.

If they match: the webhook is authentic.

If they don't: reject the webhook.

Example

HMAC Webhook Signing secret

ppro-hmac-secret

Raw payload

{"specversion":"1.0.2","source":"https://www.ppro.com","datacontenttype":"application/json","id":"XvpFAF6I7ypsaxv0xJ9BW","type":"PAYMENT_CHARGE_CREATED","subject":"charge_bcxWI3Xf7X9P3etLPUOv8","time":"2026-04-21T15:32:12.343Z","data":{"paymentChargeId":"charge_bcxWI3Xf7X9P3etLPUOv8","paymentChargeStatus":"AUTHORIZATION_PROCESSING","paymentMethod":"IDEAL","merchantId":"merch_applauselive","merchantPaymentChargeReference":"ABCD-1234-PQRS-5678","type":"PAYMENT_CHARGE_CREATED","paymentMedium":"ECOMMERCE","paymentDescriptor":"Acme Inc - Order No 12345","amount":{"value":10000,"currency":"EUR"},"consumer":{"name":"Julia Nowak","email":"[email protected]","country":"NL"},"authenticationSettings":[{"settings":{"returnUrl":"https://www.ppro.com/"},"type":"REDIRECT"}],"instrument":{"id":"instr_JKDpw81fJ8g2uPtsiI8MU","type":"BANK_ACCOUNT"}}}

PPRO-Signature

ppro-signature: t=1776785532,s=5271af077eb3525e5c50ceaa44834ff10cc6f32f6bd060e341e0dad60bae49bb

Refer Webhooks Event Payloads