Webhook - Introduction

What are Webhooks?

Webhooks are how services notify each other of events. At their core, they are just a POST request to a pre-determined endpoint that you control.

Our webhook system allows you to receive real-time notifications when important events occur in your chargeback management workflow, such as when new chargebacks are created or when existing chargebacks are updated with new information.

How Webhooks Work

Configure your endpoint: You provide a URL that can receive POST requests
Select events: Choose which event types you want to receive notifications for
Receive notifications: When events occur, we'll send HTTP POST requests to your endpoint
Process events: Your application processes the webhook payload and responds with a 2xx status code

Setting Up Webhooks

The endpoint can be whatever you want, and you can add them from the UI. You normally use one endpoint per service, and that endpoint listens to all of the event types.

For example, if you receive webhooks from our chargeback system, you can structure your URL like: https://www.example.com/chargebacks/webhooks/.

Important Implementation Notes

Response Requirements

The way to indicate that a webhook has been processed successfully is by returning a 2xx status code (200-299) response to the webhook message within a reasonable time-frame (15 seconds).

Security Considerations

Disable CSRF protection for your webhook endpoint if your framework enables it by default
Verify signatures - Always verify the webhook signature and timestamp when processing them (see the Signature Verification section for details)

Payload Structure

All webhook events follow a consistent structure and include:

Event type identifier
Timestamp of when the event occurred
Complete chargeback data payload
Unique webhook delivery ID for tracking
Your merchant UUID for identification

Ready to get started? Continue to the next sections to learn about available events, how to configure your endpoints, and best practices for handling webhook deliveries.