Skip to main content
Webhooks allow you to receive automatic notifications about payout events in real-time. When a payout status changes, WEpayments will send a POST request to your registered webhook URL with the updated transaction data.

​
How It Works

  1. Configure your notification URL when creating the payout payment using the notification_url parameter
  2. Receive notifications automatically when payout status changes
  3. Process the payload containing the complete payout details
  4. Return a 200 OK response to acknowledge receipt

​
Setting Up Webhooks

To receive webhook notifications for payout transactions, include the notification_url parameter when creating a payment: 
{
  "invoice": "ORDER-12345",
  "notification_url": "https://your-domain.com/webhooks/payout",
  "payment_method": "PIX",
  "amount": 100.00,
  "currency": "BRL",
  "country": "BR",
  "beneficiary": { ... }
}
The notification URL is defined in the notification_url field in the request body when creating a payment. Each payment can have its own notification URL, allowing you to route notifications to different endpoints based on your needs.

​
Webhook Payload

When a payout status changes, you’ll receive a POST request with the following data:

​
Response Fields

​
id
integer
Payout IDExample: 2322977
​
invoice
string
Payout invoiceExample: 575e8327-f145-48ff-b207-737eef2d6f3f
​
end_to_end
string
Payout end-to-endExample: END-TO-END-ID
​
status
object
Object that contains the current status of your payout.
​
updated_at
string
Last update of your payout.Format: <date-time>Example: 2024-09-25 15:55:18
​
status_detail
object
This object will only be returned if the payout is canceled and the merchant is using the “Account Mismatch” functionality. It provides more details on the reason for the cancellation.

​
Example Payload

{
  "id": 2322977,
  "invoice": "575e8327-f145-48ff-b207-737eef2d6f3f",
  "status": {
    "id": 6,
    "name": "Cancelled"
  },
  "updated_at": "2024-09-25 15:55:18",
  "status_detail": {
    "code": "WE0001",
    "detail": "The payment was made to an unregistered account"
  }
}

​
Status Codes

Common payout status codes:
Status IDStatus NameDescription
1CreatedPayout has been created
2ProcessingPayout is being processed
3PaidPayout has been paid successfully
4FailedPayout failed
5RejectedPayout rejected by compliance
6CancelledPayout was cancelled
See Payout Status Flow for detailed status information.

​
Webhook Endpoint Requirements

Your webhook endpoint must:
  • Accept POST requests - All webhook notifications are sent via POST
  • Use HTTPS - Only secure HTTPS URLs are accepted
  • Return 200 OK - Respond with a 200 status code within 5 seconds
  • Be publicly accessible - The endpoint must be reachable from the internet

​
Best Practices

Always Respond 200 OK: Your endpoint must respond with HTTP 200 to acknowledge receipt. Otherwise, WEpayments will retry sending the webhook.
Validate Webhook Signature: In production, always validate the webhook signature to ensure it’s from WEpayments. See Webhook Signature Documentation for details.
Process Asynchronously: Handle webhook processing asynchronously to respond quickly and avoid timeouts.
If the API returns a Canceled, Failed, or Rejected status, a new invoice must be generated. These statuses indicate that the record has already been processed and persisted in our database, preventing any modifications or retries using the same identifier.
Re-submission Policy: INVALID_DATA: You may resubmit the same payload in a new request only if the payment status is INVALID_DATA. This status occurs when banking details are incorrect (provided validation is enabled for the merchant). Other Statuses: All other statuses will trigger a duplication block if an invoice with the same data already exists.

Status Flow

Understand payout status lifecycle