Notifications

Receive notifications about any changes related to your payments.

About notifications

The Unzer API gives you a convenient way to receive customized notifications from the Unzer system: webhooks.

To keep your app or website up to date with any changes happening to your payments, you can register a webhook triggered by relevant events.

To send notifications, we’re using the standard the standard HTTP/1.1 protocol.

For the full list of webhook events supported by the Unzer API, go to Supported webhook events.

Set up your webhooks

Step 1: Whitelist the Unzer IPs

All Unzer API webhook events come from one of the following IP addresses:

  • 3.120.62.83
  • 18.196.35.212

Step 2: Prepare your API

Make your RESTful API ready for the Unzer API notifications.

API requirements

Your RESTful API needs to:

  • Accept text/plain content type requests
  • Respond with the standard HTTP 200 OK success code, to prevent notification resends
  • Have no security checks (e.g. HTTP basic authentication)

Notification examples

You’ll get notifications based on your public key, as a JSON payload. For example:

{
   "event":"types",
   "publicKey":"s-pub-xxxxxxxxxx",
   "retrieveUrl":"https://api.unzer.com/v1/types/card/s-crd-88xu7qjboupc"
}
{
  "event":"payment.pending",
  "publicKey":"s-pub-xxxxxxxxxx",
  "retrieveUrl":"https://api.unzer.com/v1/payments/s-pay-774",
  "paymentId":"s-pay-774"
}
Key Description
event The type of the event.

For the full list of webhook events supported by the Unzer API, go to Supported webhook events.
publicKey Your public key.
retrieveUrl The URL to retrieve the related payment type.
paymentId The ID of the related payment.

Error handling

If our system doesn’t receive the standard HTTP 200 OK success code within 20 seconds, it tries to resend the notification in the following intervals:

Retry attempt Interval
1 1-2 minutes after the initial webhook event
2 5-6 minutes after the 1st retry attempt
3 10-11 minutes after the 2nd retry attempt
4 30-31 minutes after the 3rd retry attempt
5 60-61 minutes after the 4th retry attempt
6-16 (10 times) Every 60 minutes

If your API doesn’t respond after the last retry attempt, the notification gets marked as undeliverable, and you can’t retrieve it anymore.

Step 3: Register your URL and choose your event types

Register a URL to which you want to get notifications, and specify the events that you want to get notified about.

Make a webhooks POST call, with the following parameters in the request body:

Parameter Required Type Default Description Example
url Yes String / The URL of the API endpoint to which you wan to get notifications. https://www.url.de/not
event Yes
(either event or eventList)
String / The types of events that you want to get notified about.

For the full list of webhook events supported by the Unzer API, go to Supported webhook events.
all
POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.de/notifications",
  "event": "all"
}

All events

To get notified about every single event, set event to all, for example:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.de/notifications",
  "event": "all"
}
response:
{
  "id": "s-whk-1",
  "event": "all",
  "url": "https://www.yourApiUrl.de/notifications"
}
Private key
To access customer data, you need to use your private key.

Selected event types

To get notified about selected event types, use eventList:

POST https://api.unzer.com/v1/webhooks
{
  "url": "https://www.yourApiUrl.de/notifications",
  "eventList": [
      "authorize", "charge", "types"
  ]
}
{
    "events": [
        {
         "id": "s-whk-2",
         "url": "https://www.yourApiUrl.de/notifications",
         "event": "authorize"
       },
       {
         "id": "s-whk-3",
         "url": "https://www.yourApiUrl.de/notifications",
         "event": "charge"
       },
       {
         "id": "s-whk-4",
         "url": "https://www.yourApiUrl.de/notifications",
         "event": "types"
       }
    ]
}
event & eventList
You can’t declare both event and eventList in a single request.

For the full list of webhook events supported by the Unzer API, go to Supported webhook events.

For information on managing your webhooks, go to Webhooks.