Webhooks and Eventhandling

In order to keep your shop up-to-date with any changes concerning your payments you can register a webhook to several different events as described here.

Single Webhook actions

Register a Webhook event

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$webhook = $heidelpay->createWebhook(

Fetch and update a Webhook

The URL of a webhook can be updated as shown in the following example.

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

// fetch
$webhook = $heidelpay->fetchWebhook('s-whk-1533');

// update
It is not possible to update the event a webhook is registered for at the moment.

Delete an existing Webhook

You can delete a webhook either by passing its id or the corresponding webhook object to the heidelpay::deleteWebhook method.

// delete a webhook by id

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

// delete a webhook by object

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$webhook = $heidelpay->fetchWebhook('s-whk-1533');

Multiple webhooks actions

Register multiple webhooks at once

In order to register multiple webhooks at once you can pass an array containing all desired events.

It will return an array containing all created webhooks as \heidelpayPHP\Resources\Webhook instances.

// register several webhooks at once

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$registeredWebhooks = $heidelpay->registerMultipleWebhooks(

Fetch all registered Webhooks at once

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$registeredWebhooks = $heidelpay->fetchAllWebhooks();

Delete all Webhooks at once

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');


Handle incoming events

Whenever an event is triggered the corresponding URL is called. The POST request contains the json-information about the event which you can use to fetch the corresponding resource which in turn can be used to update the state of the order/payment in your shop.

Just add the following code to the controller of the URL you registered, fetch the json from the event payload and inject it to the method heidelpay::fetchResourceFromEvent.

The method will fetch the corresponding resource object and return it.

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$jsonRequest = file_get_contents('php://input');
$resource = $heidelpay->fetchResourceFromEvent($jsonRequest);

After that you can determine the type of the resource and handle it accordingly.

Please refer to the latest integration examples for a working example implementation of webhooks and the event handling.

Acknowledging an event

In order to releave our webhook servers and message queues from your events, we need you to acknowledge them by returning the HTTP success code (200). This will tell the server that you have successfully received the event and there is no need to send it again.

We recommend you to use one of the following ways to handle and acknowledge incoming events.

  1. Store the event, acknowledge it and handle it later (e. g. via cron job) …
  2. … or handle the event right away and return a HTTP error code (>= 400) if something goes wrong. The Webhook server will place the event in its queue taking care of resending it again later.
What ever way you choose please do not place the event handling into a loop to try again after an error. This can create a great amount of traffic when our servers suffer a high load and add even more. In addition this can lead to a timeout where the webhook server stops the request and retries sending the event later on while your event handler retries fetching the resource from us.

Security Considerations

To make sure nobody can meddle with your payments or find out your private key please make sure to remember the following rules concerning the event handling.

don't ...
…use the event name as indicator for the state of a resource

Since there is no guarantee an event has actually been sent by our API you should always fetch the resource using the SDK. This way you make sure a hacker can not inject a false payment state into your shop. In Addition there is no guarantee the events arrive in the same order they have been sent in. Fetching the resource to an event always gives you the latest state.

don't ...
…use the events retrieveUrl to fetch the event resource without making sure the domain is legit.

A hacker could send an event with a retrieveUrl which contains his own domain to spy out your private key or to return fake data to make you believe a payment has been completed when it actually has not. Please use the method fetchResourceFromEvent(...) of the Unzer facade to retrieve the resource from an event to make sure nobody can feed you false data. This method omits the possibly manipulated domain and just uses the path to the corresponding resource, making sure you are calling a save Unzer domain.