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.
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx'); $webhook = $heidelpay->createWebhook( 'https://www.heidelpay.com', \heidelpayPHP\Constants\WebhookEvents::AUTHORIZE );
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 $webhook->setUrl('https://dev.heidelpay.de'); $heidelpay->updateWebhook($webhook);
It is not possible to update the event a webhook is registered for at the moment.
You can delete a webhook either by passing its id or the corresponding webhook object to the
// delete a webhook by id $heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx'); $heidelpay->deleteWebhook('s-whk-1533');
// delete a webhook by object $heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx'); $webhook = $heidelpay->fetchWebhook('s-whk-1533'); $heidelpay->deleteWebhook($webhook);
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
// register several webhooks at once $heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx'); $registeredWebhooks = $heidelpay->registerMultipleWebhooks( 'https://dev.heidelpay.com', [ \heidelpayPHP\Constants\WebhookEvents::AUTHORIZE, \heidelpayPHP\Constants\WebhookEvents::CHARGE, \heidelpayPHP\Constants\WebhookEvents::SHIPMENT ] );
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx'); $registeredWebhooks = $heidelpay->fetchAllWebhooks();
$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx'); $heidelpay->deleteAllWebhooks();
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
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.
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.
- Store the event, acknowledge it and handle it later (e. g. via cron job) …
- … 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.
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.
…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.
…use the events
retrieveUrlto 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.