🔄 Webhooks

Sempre que uma transação, checkout ou transferência muda de status, a Beehive envia automaticamente uma notificação HTTP (POST) para a URL que você informar no campo postbackUrl. Essa URL deve ser um endpoint do seu sistema capaz de:

receber JSON via POST
validar e armazenar o evento
processar atualizações conforme sua lógica de negócio

Os postbacks permitem que seu sistema seja atualizado em tempo real, sem precisar ficar consultando a API.

🧩 Estrutura do Payload

Todos os postbacks seguem um formato padrão:

{
  "id": <id do evento>,
  "type": "<transaction | checkout | transfer>",
  "objectId": "<id do objeto relacionado>",
  "url": "<sua URL de postback>",
  "data": {
      /* objeto completo com os detalhes do evento */
  }
}

O campo data contém todas as informações da transação, checkout ou transferência no momento da atualização. Abaixo, os 3 formatos completos para cada tipo de evento.

🟧 1. Postback de Transação (type: “transaction”)

Esse evento é enviado sempre que uma transação muda de status — por exemplo:

created
processing
authorized
paid
refused
refunded

Exemplo completo:

{
    "id": 686401,
    "type": "transaction",
    "objectId": "282",
    "url": "https://test.com",
    "data": {
        "id": 282,
        "amount": 10000,
        "refundedAmount": 0,
        "companyId": 2,
        "installments": 12,
        "paymentMethod": "credit_card",
        "status": "paid",
        "postbackUrl": null,
        "metadata": null,
        "traceable": false,
        "secureId": "a4594817-be48-4a23-81aa-4bb01f95fe78",
        "secureUrl": "https://link.compra.com.br/pagar/a4594817-be48-4a23-81aa-4bb01f95fe78",
        "createdAt": "2022-07-18T09:54:22.000Z",
        "updatedAt": "2022-07-18T09:54:22.000Z",
        "paidAt": "2022-07-18T09:54:22.000Z",
        "ip": null,
        "externalRef": null,
        "customer": {
            "id": 1,
            "externalRef": null,
            "name": "Gabryel",
            "email": "gabryel@hotmail.com",
            "phone": "11999999999",
            "birthdate": null,
            "createdAt": "2022-05-26T19:17:48.000Z",
            "document": {
                "number": "12345678910",
                "type": "cpf"
            },
            "address": {
                "street": "Rua República Argentina",
                "streetNumber": "4214",
                "complement": null,
                "zipCode": "11065030",
                "neighborhood": "Pompéia",
                "city": "Santos",
                "state": "SP",
                "country": "BR"
            }
        },
        "card": {
            "id": 147,
            "brand": "visa",
            "holderName": "GABRYEL FERREIRA",
            "lastDigits": "1111",
            "expirationMonth": 3,
            "expirationYear": 2028,
            "reusable": true,
            "createdAt": "2022-07-17T18:08:11.000Z"
        },
        "boleto": null,
        "pix": null,
        "shipping": null,
        "refusedReason": null,
        "items": [
            {
                "externalRef": null,
                "title": "b456",
                "unitPrice": 100,
                "quantity": 1,
                "tangible": false
            }
        ],
        "splits": [
            {
                "recipientId": 1,
                "amount": 10000,
                "netAmount": 9400
            }
        ],
        "refunds": [],
        "delivery": null,
        "fee": {
            "fixedAmount": 200,
            "spreadPercentage": 4,
            "estimatedFee": 600,
            "netAmount": 9400
        }
    }
}

🟦 2. Postback de Checkout (type: “checkout”)

Esse evento é disparado quando um checkout criado via Link de Pagamento é atualizado — por exemplo:

ativação
atualização dos itens
ligação com a transação finalizada

Ele inclui tanto o objeto checkout quanto a transação associada (se existir). Exemplo completo:

{
    "id": 686401,
    "type": "checkout",
    "objectId": "3",
    "url": "https://test.com",
    "data": {
        "id": 3,
        "companyId": 2,
        "description": null,
        "amount": 1000,
        "secureId": "019c2702-6fbe-4199-b21c-c9342888d6ec",
        "secureUrl": "https://link.compra.com.br/checkout/019c2702-6fbe-4199-b21c-c9342888d6ec",
        "postbackUrl": "https://test.com",
        "createdAt": "2022-08-02T18:04:04.000Z",
        "settings": {
            "defaultPaymentMethod": "credit_card",
            "requestAddress": false,
            "requestPhone": true,
            "requestDocument": true,
            "traceable": false,
            "card": {
                "enabled": true,
                "freeInstallments": 1,
                "maxInstallments": 12
            },
            "boleto": {
                "enabled": false,
                "expiresInDays": 2
            },
            "pix": {
                "enabled": true,
                "expiresInDays": 2
            }
        },
        "items": [
            {
                "externalRef": null,
                "title": "Hamburgão",
                "unitPrice": 3000,
                "quantity": 1,
                "tangible": true
            }
        ],
        "splits": [],
        "transaction": {
            "id": 282,
            "amount": 10000,
            "refundedAmount": 0,
            "companyId": 2,
            "installments": 12,
            "paymentMethod": "credit_card",
            "status": "paid",
            "postbackUrl": null,
            "metadata": null,
            "traceable": false,
            "secureId": "a4594817-be48-4a23-81aa-4bb01f95fe78",
            "secureUrl": "https://link.compra.com.br/pagar/a4594817-be48-4a23-81aa-4bb01f95fe78",
            "createdAt": "2022-07-18T09:54:22.000Z",
            "updatedAt": "2022-07-18T09:54:22.000Z",
            "paidAt": "2022-07-18T09:54:22.000Z",
            "ip": null,
            "externalRef": null,
            "customer": {
                "id": 1,
                "externalRef": null,
                "name": "Gabryel",
                "email": "gabryel@hotmail.com",
                "phone": "11999999999",
                "birthdate": null,
                "createdAt": "2022-05-26T19:17:48.000Z",
                "document": {
                    "number": "12345678910",
                    "type": "cpf"
                },
                "address": {
                    "street": "Rua República Argentina",
                    "streetNumber": "4214",
                    "complement": null,
                    "zipCode": "11065030",
                    "neighborhood": "Pompéia",
                    "city": "Santos",
                    "state": "SP",
                    "country": "BR"
                }
            },
            "card": {
                "id": 147,
                "brand": "visa",
                "holderName": "GABRYEL FERREIRA",
                "lastDigits": "1111",
                "expirationMonth": 3,
                "expirationYear": 2028,
                "reusable": true,
                "createdAt": "2022-07-17T18:08:11.000Z"
            },
            "boleto": null,
            "pix": null,
            "shipping": null,
            "refusedReason": null,
            "items": [
                {
                    "externalRef": null,
                    "title": "b456",
                    "unitPrice": 100,
                    "quantity": 1,
                    "tangible": false
                }
            ],
            "splits": [
                {
                    "recipientId": 1,
                    "amount": 10000,
                    "netAmount": 9400
                }
            ],
            "refunds": [],
            "delivery": null,
            "fee": {
                "fixedAmount": 200,
                "spreadPercentage": 4,
                "estimatedFee": 600,
                "netAmount": 9400
            }
        }
    }
}

🟩 3. Postback de Transferência (type: “transfer”)

Enviado quando uma transferência (Pix, TED, repasse interno) muda de status. Alguns exemplos de status:

bank_processing
processed
failed
transferred

Exemplo completo:

{
    "id": 388,
    "type": "transfer",
    "objectId": "237",
    "url": "https://test.com",
    "data": {
        "id": 237,
        "amount": 500,
        "status": "bank_processing",
        "pixKey": "12345678900",
        "fee": 0,
        "bankAccount": null,
        "metadata": null,
        "createdAt": "2022-10-18T16:43:42.000Z",
        "updatedAt": "2022-10-18T16:43:44.000Z",
        "failReason": null,
        "receiptUrl": null,
        "description": "Transferência Teste",
        "externalRef": null,
        "postbackUrl": "https://test.com",
        "processedAt": "2022-10-18T16:43:44.000Z",
        "recipientId": 1,
        "pixEnd2EndId": "E277287121G6I8886MF02JNCUGGLELRP",
        "transferredAt": null
    }
}

Introdução

IA

Integração

Webhook

🔄 Webhooks

🧩 Estrutura do Payload

🟧 1. Postback de Transação (type: “transaction”)

🟦 2. Postback de Checkout (type: “checkout”)

🟩 3. Postback de Transferência (type: “transfer”)

​🔄 Webhooks

​🧩 Estrutura do Payload

​🟧 1. Postback de Transação (type: “transaction”)

​🟦 2. Postback de Checkout (type: “checkout”)

​🟩 3. Postback de Transferência (type: “transfer”)

🔄 Webhooks

🧩 Estrutura do Payload

🟧 1. Postback de Transação (type: “transaction”)

🟦 2. Postback de Checkout (type: “checkout”)

🟩 3. Postback de Transferência (type: “transfer”)