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.
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $webhook = $unzer->createWebhook('https://your.notification.handler.url', UnzerSDK\Constants\WebhookEvents::AUTHORIZE);
The URL of a webhook can be updated as shown in the following example.
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $webhook = $unzer->fetchWebhook('s-whk-1533'); $webhook->setUrl('https://your.notification.handler.url'); $unzer->updateWebhook($webhook);
You can delete a webhook either by passing its ID or the corresponding webhook object to the
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $unzer->deleteWebhook('s-whk-1533');
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $webhook = $unzer->fetchWebhook('s-whk-1533'); $unzer->deleteWebhook($webhook);
In order to register multiple webhooks at once you can pass an array containing all desired events to the
The will return an array containing all created webhooks as
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $webhooks = $unzer->registerMultipleWebhooks( 'https://your.notification.handler.url', [ UnzerSDK\Constants\WebhookEvents::AUTHORIZE, UnzerSDK\Constants\WebhookEvents::CHARGE, UnzerSDK\Constants\WebhookEvents::SHIPMENT ] );
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $webhooks = $unzer->fetchAllWebhooks();
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $unzer->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 handler 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.
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx'); $jsonRequest = file_get_contents('php://input'); $resource = $unzer->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 to use one of the following ways to handle and acknowledge incoming events:
- Store the event in a queue, acknowledge it and handle it later (e. g. via cron job)
- Handle the event right away and return 200 if it is a success and a HTTP error code (>= 400) if something goes wrong. In case you return an error code the webhook servers will place the event in the queue taking care of resending it [again later]](/get-started/basics/notifications/).
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 in which they occurred. 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 class 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.