Overview

What are Webhooks?

Webhooks allow your application to receive real-time notifications whenever important events occur inside the MagenPay platform. Instead of polling our APIs, you can configure a webhook endpoint and MagenPay will automatically send an HTTP POST request each time an event is triggered.

Webhooks are commonly used to update internal systems, notify your users, trigger business rules or reconcile transactions.

How It Works

Whenever an event happens (e.g., a PIX is received or a reversal is processed), MagenPay generates an event.

MagenPay sends a POST request to your webhook endpoint with the event payload.

Your system processes the event.

Your endpoint must return a 2xx HTTP status code to acknowledge successful receipt.

If we receive any non-2xx response, the delivery will be retried.

Event Structure

All webhook payloads follow the same envelope format:

{
  "type": "pixRequestIn",
  "data": {
    "description": "pix-in",
    "debtor": {
      "document": "123.456.789-00",
      "name": "Fulano de tal",
      "accountType": "payment",
      "ispb": "12345678",
      "branch": "0000",
      "account": "000001"
    },
    "creditor": {
      "document": "01.002.601/0001-15",
      "name": "Empresa Teste LTDA",
      "accountType": "payment",
      "ispb": "12345678",
      "branch": "0001",
      "account": "001001"
    },
    "flow": "IN",
    "amount": 1.1,
    "status": "success",
    "endToEndId": "E12345678202511141421t19284qFoto",
    "txId": "",
    "finishedAt": "2025-11-14T14:56:45.821Z",
    "externalId": "",
    "method": "dict",
    "transactionType": "PIX",
    "metadata": {
      "reason": null,
      "triggerTransactionId": null
    }
  }
}

Fields

Available Events

The following types of events can currently be delivered:

pixRequestIn — Inbound PIX received

pixRequestOut — Outbound PIX sent

pixReversalIn — Incoming PIX reversal

pixReversalOut — Outgoing PIX reversal

A full description of these events is available in the Events section below.