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. This guide shows you how to create and manage webhook subscriptions.

​
Create a webhook subscription

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

POST /webhooks/subscriptions

Request parameters:

​
title
string
required

The label to help you distinguish one webhook from another.

​
url
string
required

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

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

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.

​
enabled
boolean

Whether the subscription should be enabled immediately. Defaults to true.

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

Response fields:

​
id
string
required

Unique identifier for the webhook subscription.

​
title
string
required

The title you provided for the subscription.

​
enabled
boolean
required

Whether the subscription is currently enabled and will receive events.

​
url
string
required

The endpoint URL where events will be delivered.

​
events
array
required

List of event types this subscription will receive.

​
secret
string
required

The signing secret for verifying webhook requests. This is only returned once at creation time.

The secret field 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.

​
Enable and disable subscriptions

You can control whether a subscription actively receives events using the enabled field. Webhook subscriptions are created enabled by default and will immediately start receiving events unless you explicitly set enabled: false during creation.

1

Create disabled subscription

Set enabled: false in your creation request to create a subscription that won’t immediately start receiving events.

POST /webhooks/subscriptions

Request
{
  "title": "Test webhook",
  "enabled": false,
  "url": "https://tenant.tld/webhooks",
  "events": ["RECIPIENT.CREATED"]
}
2

Enable when ready

Use a PATCH request to enable the subscription when your handler is ready to process incoming requests.

PATCH /webhooks/subscriptions/{subscriptionId}

Request
{
  "enabled": true
}