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 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
This 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
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.
To relieve 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 using 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.
To secure your payments and prevent unethical parties from accessing your private key, the following rules apply.
Because there is no guarantee an event you received has been sent by Unzer API and not a third party, you must always fetch the resource using the SDK. This way you make sure a hacker cannot inject a false payment state into your shop. You should always fetch the resource to get the latest state because the events may arrive in a random order.
retrieveUrlto fetch the event resource before confirming a legitimate domain
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 only uses the path to the corresponding resource, making sure you are calling a save Unzer domain.