Skip to main content

Webhooks for authorizations

These webhooks are related to the authorization flow

Events​

walley:authorization:created​

This webhook is triggered whenever an authorization is created using the authorization endpoint.

{
  "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"
  }
}

walley:authorization:authorized​

This webhook is triggered whenever an authorization is successful, and will be closely followed by a walley:order:created webhook.

{
  "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"
  }
}

walley:authorization: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.

{
  "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"
  }
}

walley:authorization: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.

{
  "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"
  }
}

Webhook best practices​

walley:authorization:created​

Triggered when an authorization is created.

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:authorization:authorized​

Triggered when an authorization succeeds. This event is closely followed by walley:order:created.

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:authorization:retrying​

Triggered when an authorization attempt was unsuccessful, but additional attempts will be made according to the configured attempt schedule.

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:authorization:failed​

Triggered when an authorization attempt is unsuccessful and no further attempts will be made (final attempt or unsolvable failure).

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.