PaySway manages webhooks through webhook subscriptions, each of which has its own callback URL, event filter, and other optional metadata to help you organize and secure your integrations. Below is an overview of how to create a new subscription and the rules you’ll need to follow.

​
Required information

1

Title

The label to help you distinguish one webhook from another.

2

URL

The HTTPS endpoint URL where events are delivered. Important constraints are:

  • URL Scheme: Only HTTPS is supported.
  • Host Requirement: The host portion of the URL must be a valid domain name (IP addresses are not allowed)
  • No Redirects: Your endpoint must not respond with HTTP 3xx codes.
3

Event types

The list of event types you want to receive webhooks for. Providing an empty event types list means no events will be delivered to that subscription.

​
Managing subscriptions

To register a webhook subscription, send the following request describing your new webhook:

POST /webhooks/subscriptions

{
  "title": "Recipient webhook",
  "enabled": true,
  "url": "https://tenant.tld/webhooks",
  "events": [
    "RECIPIENT.CREATED",
    "RECIPIENT.DELETED",
    "RECIPIENT.UPDATED"
  ]
}

After creating a subscription, PaySway returns a unique identifier, along with your subscription details. Notably, it also provides a secret field, which is critical for verifying signatures of webhook requests. This secret is only returned once at the time of creation, so be sure to save it in a secure location. If you lose the secret, you will need to create a new subscription.

You can specify whether a new subscription is enabled or disabled using the enabled field in the request body. To enable a previously disabled subscription, submit a PATCH request as outlined in the API reference. Once enabled, PaySway will begin sending the specified event types to your URL. Ensure your handler is fully prepared to process incoming requests before enabling the subscription.