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.

Single Webhook actions

Register a Webhook event

$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$webhook = $unzer->createWebhook('https://your.notification.handler.url', UnzerSDK\Constants\WebhookEvents::AUTHORIZE);

Fetch and update a Webhook

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);
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 Unzer::deleteWebhook method.

$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);

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 to the Unzer::registerMultipleWebhooks method. This will return an array containing all created webhooks as UnzerSDK\Resources\Webhook instances.

$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
        ]
);

Fetch all registered Webhooks

$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$webhooks = $unzer->fetchAllWebhooks();

Delete all Webhooks at once

$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$unzer->deleteAllWebhooks();

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 handler of the URL you registered, fetch the JSON from the event payload and inject it to the Unzer::fetchResourceFromEvent 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.

Acknowledging an event

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:

  1. Store the event in a queue, acknowledge it and handle it later (e. g. via cron job)
  2. 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.

Security Considerations

To secure your payments and prevent unethical parties from accessing your private key, the following rules apply.

Don’t use the event name as indicator for the state of a resource

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.

Don’t use the events retrieveUrl to 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.