Documentação de Webhooks: eventos e payloads
Esta é a referência técnica dos webhooks da Cloudfy. Sempre que algo acontece em um pedido (PIX gerado, pagamento aprovado, reembolso, etc.), a Cloudfy envia uma requisição POST para a URL que você cadastrou em Webhooks, com um corpo JSON no formato abaixo. Para cadastrar a URL, veja Como configurar um webhook?.
Baixar a documentação completa (PDF)
Formato do evento
Todo evento chega com dois campos no nível raiz: type (o nome do evento) e payload (os dados do pedido).
{
"type": "PIX_APPROVED",
"payload": { ... }
}Eventos disponíveis
Evento (type) | Quando dispara |
|---|---|
PIX_GENERATED | PIX gerado, aguardando pagamento (status PENDING). |
PIX_APPROVED | PIX pago e aprovado (status APPROVED). |
PIX_EXPIRED | PIX expirou sem pagamento. |
BOLETO_GENERATED | Boleto gerado, aguardando pagamento (status PENDING). |
BOLETO_APPROVED | Boleto pago e aprovado (status APPROVED). |
CREDIT_CARD_APPROVED | Pagamento no cartão aprovado (status APPROVED). |
CREDIT_CARD_REFUSED | Pagamento no cartão recusado (status REFUSED). |
ORDER_REFUNDED | Pedido reembolsado (status REFUNDED). |
ORDER_CHARGED_BACK | Pedido sofreu chargeback (status CHARGED_BACK). |
CHECKOUT_ABANDONED | Checkout abandonado — o cliente preencheu os dados mas não finalizou o pagamento. |
Campos do payload (eventos de pedido)
Os eventos de PIX, boleto e cartão compartilham a mesma estrutura de payload:
| Campo | Descrição |
|---|---|
_id | ID do pedido. |
value | Valor do pedido. |
items[] | Lista de itens, cada um com product (name, description, img.url) e quantity. |
paymentMethod | Método de pagamento: PIX, BOLETO ou CREDIT_CARD. |
payerName | Nome de quem pagou. |
payerCpf | CPF de quem pagou. |
payerEmail | E-mail de quem pagou. |
phone | Telefone de quem pagou. |
installments | Número de parcelas. |
status | Status do pedido: PENDING, APPROVED, REFUSED, REFUNDED ou CHARGED_BACK. |
store | ID da loja. |
createdAt / updatedAt | Datas de criação e atualização do pedido. |
orderPendingUrl | Link do pedido pendente. |
Campos específicos do PIX
Presentes nos eventos PIX_GENERATED, PIX_APPROVED e PIX_EXPIRED:
qrCode— código copia e cola do PIX.base64QrCode— imagem do QR Code em base64.pixDueDate— validade do PIX.
Campos específicos do boleto
Presentes nos eventos BOLETO_GENERATED e BOLETO_APPROVED:
barCode— código de barras.digitableLine— linha digitável.externalResourceUrl— link para acessar o boleto.boletoDueDate— vencimento do boleto.
Objeto shipping (entrega)
Quando há endereço de entrega, o payload inclui o objeto shipping com: value, street, neighborhood, city, state, number, cep, type, complement, selectedShippingId, createdAt e updatedAt.
Parâmetros de rastreamento
A Cloudfy captura automaticamente os parâmetros enviados na URL do checkout e os repassa no payload do webhook.
| Parâmetro na URL | Campo no payload |
|---|---|
utm_source | utmSource |
utm_campaign | utmCampaign |
utm_medium | utmMedium |
utm_content | utmContent |
utm_term | utmTerm |
click_id (Kwai Ads) | kwaiClickId |
ttclid (TikTok Ads) | tiktokClickId |
Também podem ser enviados xcod e subIds.
Campos opcionais
Os campos abaixo são opcionais e podem não estar presentes, vir como null ou como string vazia, dependendo de como o checkout foi acessado:
utmSource, utmCampaign, utmMedium, utmContent, utmTerm, xcod, subIds, kwaiClickId, tiktokClickId, shipping e orderPendingUrl.
Exemplo: PIX_APPROVED
{
"type": "PIX_APPROVED",
"payload": {
"_id": "673a3dca2b11ddfb67e3315c",
"value": 15,
"items": [
{ "product": { "name": "Teclado gamer", "description": "lorem", "img": { "url": "image do produto" } }, "quantity": 1 }
],
"paymentMethod": "PIX",
"payerName": "Sérgio Antonio",
"payerCpf": "087.001.240-10",
"installments": 1,
"status": "APPROVED",
"store": "66f5572e4b28b122deaa9840",
"qrCode": "pixCopiaECola",
"base64QrCode": "imagemDoQrCodeEmBase64",
"pixDueDate": "2024-11-17T19:12:34.724Z",
"phone": "(85) 98902-8127",
"payerEmail": "sergio@gmail.com",
"shipping": { "value": 14.9, "number": 123, "type": "FIXED" },
"orderPendingUrl": "https://..."
}
}Evento CHECKOUT_ABANDONED
Esse evento tem um payload diferente — todos os campos são opcionais (podem vir como undefined):
{
"type": "CHECKOUT_ABANDONED",
"payload": {
"storeId": "66f5572e4b28b122deaa9840",
"document": "632.444.900-93",
"email": "joao@gmail.com",
"fullName": "Joao Silva",
"phone": "(11) 1 1111-1111"
}
}