Setup your webhooks
Integrate Klarna Webhooks to receive real-time business event notifications, ensuring secure, responsive, and well-maintained backend operations.
Klarna webhooks enable your applications to receive real-time business event notifications from the integrated Klarna product suite, allowing your backend systems to respond promptly.
Webhooks are customizable, and all Klarna APIs include a standard set of webhook events to which you can subscribe. For a list of supported event types, refer to the list of event categories listed in the Create and manage webhooks section below.
Consult the API reference
for a complete description of the request body parameters.
for a complete description of the request body parameters.Getting started with Klarna webhooks
To maintain seamless integration with Klarna's Payment Services and ensure your systems are equipped to handle Klarna notifications effectively, follow these steps:
1. Establish a secure endpoint
- Expose an HTTPS endpoint on your server designed to receive webhook notifications.
- Ensure only HTTPS endpoints are used and that a valid SSL certificate is in place.
- Expose the endpoint on port 443 or 8443 only. Requests sent to other ports won't be delivered, as webhook traffic is routed through a proxy with restricted port support.
2. Endpoint Configuration
- Configure a single endpoint for multiple event types or set up separate endpoints for each event type based on your preferences.
3. Receive Notifications
- Ensure the endpoint is reachable over HTTPS on port 443 or 8443.
- Verify HMAC Signature to ensure data security and integrity.
- See more info in the Create and manage signing keys section.
- Store the webhook event data for further processing. Sample webhook request
JSON
1
2
3
4
5
6
7
8
9
10
{
"metadata": {
"event_type": "event_type",
"event_id": "unique event UUID",
"event_version": "v2",
"occurred_at": "2025-02-28T12:00:00Z",
"subject_account_id": "Partner account ID",
"recipient_account_id": "Acquiring Partner Account ID",
"product_instance_id": "product-specific ID",
"webhook_id": "webhook-specific ID",4. Acknowledge the webhook
Immediately respond to webhook notifications with an HTTP status code of 200, 201, 202, or 204 to confirm successful delivery.
Failure to respond, or a response with any other status code, will trigger Klarna's retry mechanism.
5. Retry mechanism
Klarna will retry notifications at increasing intervals upon failure (timeout or HTTP 4XX/5XX response codes). Klarna orchestrates these retries with progressively longer delays, which can extend up to 12 hours or until a successful response is received.
Here's how the retry schedule is structured:
- First retry: 10 seconds after the initial failure.
- Second retry: 2 minutes later.
- Third Retry: 15 minutes later.
- If the issue persists, retries are scheduled at 3 hours, 6 hours, and finally 12 hours for the last attempt.
This structured approach ensures multiple opportunities for notifications to succeed, enhancing the reliability of the communication between systems.
Handling failed notifications
If no successful response is received after the final retry attempt at 12 hours, the notification will be considered permanently failed.
Manual processing of failed notifications
If you resolve an issue on your end and need additional assistance to receive the previously failed notification, reach out to Klarna support.
When you modify webhook settings during ongoing retries, these changes will only apply to new notifications. If a triggered Klarna webhook fails to receive a response code of 200, 201, 202, or 204, it will continue to retry using the old configuration until it either successfully communicates or reaches the 12-hour retry limit.
sequenceDiagram
participant A as KLARNA
participant B as ACQUIRING PARTNER
autonumber
A ->> B: Send webhook
Note over A, B: POST request will be sent to the URL <br>of configured endpoint.<br><br>POST https://partner.api/receive-hook
B ->> A: Acknowledge webhook
par Acknowledged (2XX)
Note over A, B: Responses code 200, 201, 202 or 204 <br> are expected to acknowledge <br> webhook.
and Failed (Timeout,4XX,5XX)
par Retries
Note over A, B: The retry mechanism will try to deliver <br> the notification for up to 12 hours or <br>until a successful response.
A ->> B: Retry webhook
Note over A, B: Retries will contain same body and will <br> be send to the same endpoint as <br>the initial attempt.
end
end
To avoid disruptions and ensure a smooth transition, it is recommended to initiate and run a new webhook in parallel before discontinuing an older webhook. This strategy ensures that the new settings are fully operational and effective, maintaining seamless notification delivery during the transition period.
Create and manage signing keys
To securely receive webhook notifications, you must generate and attach signing keys to your webhooks. See createSigningKey for details.
for details.This procedure ensures the authenticity of incoming notifications can be verified. Klarna will sign each notification using the designated signing key before dispatch. Both the signature and its identifier will be included in the notification, enabling you to confirm its validity. When configuring a new webhook, specify the signing key to be used.
After generating signing keys, make sure to securely store them immediately. You will not be able to retrieve these keys again for webhook validation purposes.
API & SDK references