---
id: authorizations
title: "Webhooks for authorizations"
sidebar_label: "Authorizations"
hide_title: true
description: "Webhooks related to authorizations"
---

import Ingress from "../../src/components/ingress/ingress.react";

<Ingress title="Webhooks for authorizations">
  These webhooks are related to the
  <a href="/docs/checkout/tokenization/authorization">authorization flow</a>
</Ingress>

## Events

### walley&colon;authorization&colon;created

This webhook is triggered whenever an authorization is created using the [authorization endpoint](/docs/checkout/tokenization/authorization).

```json
{
  "Type": "walley:authorization:created",
  "Timestamp": "2024-01-30T10:02:31.2700113+00:00",
  "Payload": {
    "CustomerToken": "0a96881b-295a-4154-a867-865fc912619c",
    "AuthorizationId": "c31e9218-6a19-4b2f-8992-affc9dca1c41",
    "Reference": "01478520",
    "ActionReference": "Action 1234",
    "CreatedOn": "2024-01-30T10:02:31.2700113+00:00"
  }
}
```

**Do**

- Set internal status to `CREATED`.

**Do not**

- Treat this event as an authorization success or "funds reserved". It only indicates the authorization process has started.

### walley&colon;authorization&colon;authorized

This webhook is triggered whenever an authorization is successful, and will be closely followed by a [walley:order:created webhook](/docs/webhooks/orders#walleyordercreated).

```json
{
  "Type": "walley:authorization:authorized",
  "Timestamp": "2024-01-30T10:02:31.2700113+00:00",
  "Payload": {
    "CustomerToken": "0a96881b-295a-4154-a867-865fc912619c",
    "AuthorizationId": "c31e9218-6a19-4b2f-8992-affc9dca1c41",
    "Reference": "01478520",
    "ActionReference": "Action 1234",
    "CreatedOn": "2024-01-30T10:02:31.2700113+00:00"
  }
}
```

**Do**

- Update internal status to `AUTHORIZED`.
- Expect and handle the subsequent `walley:order:created` webhook to obtain the `OrderId` required for downstream order operations.

**Operational guidance**

- Alert if `walley:authorization:authorized` arrives but `walley:order:created` does not arrive within a reasonable time window.

### walley&colon;authorization&colon;retrying

This webhook is triggered whenever an authorization was unsuccessful, but there will be additional attempts according to the AttemptSchedule provided when creating the [authorization](/docs/checkout/tokenization/authorization).

```json
{
  "Type": "walley:authorization:retrying",
  "Timestamp": "2024-01-30T10:02:31.2700113+00:00",
  "Payload": {
    "CustomerToken": "0a96881b-295a-4154-a867-865fc912619c",
    "AuthorizationId": "c31e9218-6a19-4b2f-8992-affc9dca1c41",
    "Reference": "01478520",
    "ActionReference": "Action 1234",
    "CreatedOn": "2024-01-30T10:02:31.2700113+00:00",
    "CurrentAttempt": 1,
    "MaxAttempt": 5,
    "Reason": "SERVICE_UNAVAILABLE"
  }
}
```

**Do**

- Update internal status to `RETRYING`.
- Consider customer communication for customer-actionable reasons.

**Do not**

- Immediately create a new authorization on first failure; this webhook indicates Walley is already continuing attempts.

### walley&colon;authorization&colon;failed

This webhook is triggered whenever an authorization was unsuccessful, and no further attempt will be performed. Either because this was the last attempt in the AttemptSchedule, or because we deemed the failure unsolvable.

```json
{
  "Type": "walley:authorization:failed",
  "Timestamp": "2024-01-30T10:02:31.2700113+00:00",
  "Payload": {
    "CustomerToken": "0a96881b-295a-4154-a867-865fc912619c",
    "AuthorizationId": "c31e9218-6a19-4b2f-8992-affc9dca1c41",
    "Reference": "01478520",
    "ActionReference": "Action 1234",
    "CreatedOn": "2024-01-30T10:02:31.2700113+00:00",
    "CurrentAttempt": 1,
    "MaxAttempt": 5,
    "Reason": "PAYMENT_METHOD_EXPIRED"
  }
}
```

**Do**

- Update internal status to `FAILED`.
- Choose the next business action based on the reason, for example:
    - Customer action required (request updated payment method or new consent/token)
    - Token lifecycle issue (stop recurring attempts until a new token exists)
    - Send a paylink to the customer to use for payment instead.

**Do not**

- Continue retrying indefinitely on your side; this event indicates Walley will not retry further.