Webhooks

To acknowledge the webhook sent from Checkout, a 200 HTTP status code is required. Any other status code, even other 2XX codes, will be treated as an unsuccessful attempt. The response cannot take more than 10 seconds, otherwise it will be counted as an unsuccessful attempt.

If the webhook was not successfully posted to you, it will fall under the Retry mechanism described below.

One of the core tenets of webhooks is the concept of at-least-once delivery. This approach ensures that messages are always delivered. It also means that messages can be received more than once, even repeatedly and out of order. For this reason, it's important that the webhook receiver supports the idempotent consumer pattern.

Working under the assumption of at-least-once delivery, especially within the context of an event-driven architecture, is a responsible approach for reliably processing events. Your function must be idempotent so that the outcome of processing the same event multiple times is the same as processing it once.

An application that communicates with distributed elements has to be sensitive to the transient faults that can occur in this environment. Faults include the momentary loss of network connectivity to components and services, the temporary unavailability of a service, or timeouts that occur when a service is busy.

If the fault is caused by one of the more commonplace connectivity or busy failures, the network or service might need a short period while the connectivity issues are corrected or the backlog of work is cleared. In this case, we will retry for a maximum of 10 times with the following delay intervals: 2, 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90, 120, 250 minutes.

If your site still has not responded successfully after this period, the webhook will not be attempted any more.

In a distributed environment, calls to remote resources and services can fail due to transient faults, such as slow network connections, timeouts, or the resources being overcommitted or temporarily unavailable. These faults typically correct themselves after a short period of time and are handled by a Retry routine.

However, there can also be situations where faults are due to unanticipated events, and that might take much longer to fix. In these situations, it might be pointless for an application to continually retry an operation that is unlikely to succeed. Instead, the application should quickly accept that the operation has failed and handle this failure accordingly.

We will stop sending notifications once more than 20% of webhooks sent to a given endpoint fail within a 30-second timespan. We will then start probing after another 30 seconds to see if the endpoint is healthy again. All not sent notifications during the period when the circuit is open are subject to the Retry routine.

The following table lists all events that can be subscribed to using the Boarding API:

The onboarding.initiated event is triggered when an onboarding application has been initiated. After this event has triggered, the application can be edited and submitted.

Payload

Example

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "merchantNumber": 12345,
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.initated",
    "data": {
        "onboardingId": 6259,
        "status": "INITIATED"
    }
}

The onboarding.awaiting_signature event is triggered when an onboarding application has been submitted and is in the signing process.

Payload

Example

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.awaiting_signature",
    "data": {
        "onboardingId": 6259,
        "status": "AWAITING_SIGNATURE"
    }
}

The onboarding.signature_failed event is triggered when the signing process failed for or many reasons. See the property data.reason below.

Payload

Example

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-05T11:33:33.5969Z",
    "event": "onboarding.SIGNATURE_FAILED",
    "data": {
        "onboardingId": 6259,
        "status": "SIGNATURE_FAILED",
        "reason": "expired"
    }
}

The onboarding.processing event is triggered when an onboarding application has been signed by the merchant and is in the review process.

Payload

Example

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.processing",
    "data": {
        "onboardingId": 6259,
        "status": "PROCESSING"
    }
}

The onboarding.approved event is triggered when an onboarding application has been approved.

Payload

Example

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.approved",
    "data": {
        "onboardingId": 6259,
        "status": "APPROVED"
    }
}

The onboarding.abandoned event is triggered when an onboarding application has been abandoned, either because signing failed or an application was rejected.

Payload

Example

{
    "id": "fd70g9f82f9f423fa5f776092ee673c9",
    "merchantId": "1064fa1e9cc44029ae0480e107cbd32b",
    "timestamp": "2021-05-04T22:33:33.5969+02:00",
    "event": "onboarding.abandoned",
    "data": {
        "onboardingId": 6259,
        "status": "ABANDONED"
    }
}

The payment.reservation.created is an alternative to payment.reservation.created.v2. It is triggered when the amount of the payment has been reserved. But it contains more values, for instance data.cardDetails.threeDSecure.eci)

Payload

Example

{
    "id": "c25459e92ba54be1925493f987fb05a7",
    "timestamp": "2021-05-04T22:09:08.4342+02:00",
    "merchantNumber": 100017120,
    "event": "payment.reservation.created.v2",
    "data": {
        "paymentMethod": "Visa",
        "paymentType": "CARD",
        "amount": {
            "amount": 5500,
            "currency": "SEK"
        },
        "paymentId": "02a900006091a9a96937598058c4e474"
    }
}