GrailPay provides a single endpoint to both register and de-register webhook URLs for event subscriptions. This endpoint
allows you to manage your webhook configurations efficiently and programmatically. By using different request payloads,
you can either subscribe a new URL to specific events or remove an existing one from receiving notifications.
Webhook registrations are scoped to the API token you use, and each token is allowed a maximum of 10 unique webhook URLs.
If you exceed this limit or attempt to register a duplicate, the request will result in an error. Webhook events are
delivered via HTTPS POST requests, and all configured URLs must be secured over HTTPS.
For a list of all possible event names you can subscribe to, please refer to the Webhook Events
documentation.
This route is secured with processor and vendor token authentication.
Our webhooks are not specific to any particular entity in our ACH Application. So for
example, you would not want to register an individual webhook for every merchant that you onboard. Each of those
webhooks urls will get the same data each time an event is triggered. The approach we recommend is to register a
single webhook url to the events you wish to subscribe to. Then you can use the event data to determine which
entity the event is related to.
If our application detects consistent errors from any registered webhook url, we will automatically deregister
that webhook url.
Registering a Webhook
To register a webhook URL for a specific event, submit a POST request to the /v3/webhooks/register endpoint with the desired
event_name and webhook_url. Once registered, GrailPay will begin delivering event payloads to the specified URL.
If the URL is successfully registered, you’ll receive a 200 response confirming the subscription.
For full schema details, refer to:
De-Registering a Webhook
To de-register an existing webhook, send a DELETE request to the /v3/webhooks/register endpoint using the same
event_name and webhook_url that were originally registered. If a matching subscription is found, it will be removed,
and no further webhook events will be delivered to that URL.
For full schema details, refer to:
Fetch All Webhook Events
This endpoint allows you to retrieve a list of all webhook event types currently supported by the GrailPay API. Each
event in the list corresponds to a specific system action—such as a transaction starting, a refund being completed, or a
payout failing—that can trigger a webhook notification when subscribed to.
This endpoint is useful for dynamically discovering the available webhook events your integration can subscribe to,
especially when building tools for configuration, administration, or reporting. You can use the returned list to ensure
your system is aware of the full range of webhook triggers available for monitoring and automation.
For full request and response details, see the OpenAPI Documentation.
Testing
At this time, GrailPay does not support direct simulation of webhook events in the Sandbox environment. However, you
can test your webhook integration by registering a webhook URL in Sandbox and performing actions that naturally trigger
webhook events. This approach allows you to validate that your endpoint receives and processes real webhook payloads as
expected.
For more details on testing in Sandbox, refer to our Technical Overview guide.
Questions?
If you’re encountering any issues, please reach out to [email protected].
