Skip to content

Webhooks

Target Audience: Users, Developers

Introduction

This section describes the "Webhooks" functionality available within Payway.

Note: This functionality may also be known as Events or Service Bus Events.

Where can I find my webhooks?

In order to find your configured webhooks, simply navigate to PAP => Control panel => Webhooks.

How do I add a webhook?

Navigate to PAP => Control panel => Webhooks and click Create connection. Then fill in:

  • URL: The complete address Payway should send the events to. It must start with https:// and point to a public server. Each URL can only be registered once per organisation.
  • Authentication (optional): A user name and password that Payway sends with basic authentication on every call. The password is stored encrypted and is never shown again.
  • Events: The events that should be sent to the URL. Select at least one.

Events are sent to the new webhook as soon as it is saved.

How do I change a webhook?

Select the webhook in the list. You can:

  • Enable or disable events. An event you disable stops being sent at once, and its queued and failed events are removed.
  • Change the URL, for example when the receiving system moves. All selected events are kept and sent to the new URL, including events that are queued or have failed. A webhook that has been disabled after reaching the hard limit is enabled again when its URL is changed.
  • Change the authentication. Enter a new user name and password and save. Leave the password empty to keep the current one.
  • Remove the authentication. Click the trash icon next to the password and confirm. The user name and password are removed at once, and events are then sent without authentication. Changes in the form that have not been saved are lost, so save them first.

How do I delete a webhook?

Click the delete icon in the list, or Delete when editing the webhook, and confirm. All events to the URL stop being sent at once, and its queued and failed events are removed. The receiving system no longer gets any data from Payway, and this cannot be undone.

Webhooks managed by Payway

Some webhooks belong to Payway itself, for example the ones used by single sign-on and Payway's email service. They are not shown in the list and cannot be changed or deleted by administrators. Service Bus connections are shown, but can only be changed by Payway. Reach out to our support if one of them needs to change.

How do I check the status between Payway and my webhook?

In order to check the health of the connection between Payway and your registered webhook(s), simply navigate to PAP => Control panel => Webhooks, and select the endpoint you're interested in checking out.

Within this view, you will be able to find the endpoint status, as well as how many queued and/or failing events are currently trying to find their way to your endpoint.

Email notifications when an endpoint is failing

When an event endpoint starts failing, Payway will notify the administrators who hold the Superuser role/permission within your organisation via email, so that the issue can be looked into before events are lost.

Notifications are tied to two thresholds:

  • Soft limit — a warning threshold. The endpoint keeps retrying and remains active, but it has accumulated enough failing events to warrant attention. A single email is sent when this limit is reached.
  • Hard limit — the endpoint has kept failing beyond the soft limit and is now disabled, meaning events are no longer being delivered to it. A single email is sent when this limit is reached.

Note

The email is sent once per endpoint and per limit — not once per event type. In other words, regardless of how many different event types are configured on a failing endpoint, you will receive a single notification when the soft limit is reached, and a single notification when the hard limit is reached.

If you receive one of these emails, navigate to PAP => Control panel => Webhooks and select the affected endpoint to review its status and latest error message. If the endpoint has been disabled after reaching the hard limit because its URL has changed, update the URL and it is enabled again. Otherwise, please reach out to our support and we'll be glad to help you get it re-enabled.