Webhooks

Webhooks 🔄

Receive real-time updates about events in your integration through webhook notifications.

Overview

Webhooks allow your application to receive real-time notifications when specific events occur in our system. Instead of constantly polling our API for updates, webhooks push data to your application as events happen.

🚀 Setting Up Webhooks

Navigate to the "Webhooks" section

Click "Add Webhook Endpoint"

Enter the URL where you want to receive webhook notifications

Select the events you want to subscribe to

Save your webhook configuration

📬 Webhook Payload

When an event occurs, we'll send a POST request to your specified URL with a JSON payload. Here's the structure of the webhook payload:

{
  "id": "invoice_123456",
  "status": "paid",
  "total": 1990,
  "method": "pix",
  "event": "invoice.paid"
}

Payload Fields

Field	Type	Description
id	string	The unique identifier of the invoice
status	string	The current status of the invoice (e.g., "paid", "pending", "failed")
total	integer	The total amount in cents
method	string	The payment method used (e.g., "credit_card", "bank_transfer")

Responding to Webhooks

Your webhook endpoint should return a 2xx HTTP status code to acknowledge receipt of the webhook. If our system doesn't receive a 2xx response, we'll retry sending the webhook up to 3 times with an exponential backoff.

Testing Webhooks

You can test your webhook implementation using our webhook simulator in the developer dashboard. This allows you to send test payloads to your endpoint without having to trigger actual events.

Security Recommendations ⚠️

Verify webhook authenticity using the signature in the request headers

Implement proper error handling for webhook requests

Use HTTPS for your webhook endpoint

Set up monitoring to track webhook deliveries and failures

Common Webhook Events

Event	Description
invoice.created	Triggered when a new invoice is created
invoice.paid	Triggered when an invoice is paid successfully
invoice.failed	Triggered when a payment attempt fails
invoice.canceled	Triggered when an invoice is canceled

Need more help? Contact our developer support team for assistance.

Webhooks 🔄#

Overview#

🚀 Setting Up Webhooks#

📬 Webhook Payload#

Payload Fields#

Responding to Webhooks#

Testing Webhooks#

Security Recommendations ⚠️#

Common Webhook Events#