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"
}
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"
}
]
}
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.