PT Go to Cloudfy Talk to support

Webhooks documentation: events and payloads

Integrations & WebhooksUpdated on 2026-06-26

This is the technical reference for Cloudfy webhooks. Whenever something happens to an order (PIX generated, payment approved, refund, etc.), Cloudfy sends a POST request to the URL you registered under Webhooks, with a JSON body in the format below. To register the URL, see How do I set up a webhook?.

Download the full documentation (PDF)

Event format

Every event arrives with two top-level fields: type (the event name) and payload (the order data).

{
  "type": "PIX_APPROVED",
  "payload": { ... }
}

Available events

Event (type)When it fires
PIX_GENERATEDPIX generated, awaiting payment (status PENDING).
PIX_APPROVEDPIX paid and approved (status APPROVED).
PIX_EXPIREDPIX expired without payment.
BOLETO_GENERATEDBoleto generated, awaiting payment (status PENDING).
BOLETO_APPROVEDBoleto paid and approved (status APPROVED).
CREDIT_CARD_APPROVEDCard payment approved (status APPROVED).
CREDIT_CARD_REFUSEDCard payment refused (status REFUSED).
ORDER_REFUNDEDOrder refunded (status REFUNDED).
ORDER_CHARGED_BACKOrder charged back (status CHARGED_BACK).
CHECKOUT_ABANDONEDCheckout abandoned — the customer filled in their details but did not complete payment.

Payload fields (order events)

The PIX, boleto and card events share the same payload structure:

FieldDescription
_idOrder ID.
valueOrder value.
items[]List of items, each with product (name, description, img.url) and quantity.
paymentMethodPayment method: PIX, BOLETO or CREDIT_CARD.
payerNamePayer name.
payerCpfPayer CPF.
payerEmailPayer email.
phonePayer phone.
installmentsNumber of installments.
statusOrder status: PENDING, APPROVED, REFUSED, REFUNDED or CHARGED_BACK.
storeStore ID.
createdAt / updatedAtOrder creation and update dates.
orderPendingUrlPending order link.

PIX-specific fields

Present in PIX_GENERATED, PIX_APPROVED and PIX_EXPIRED:

  • qrCode — PIX copy-and-paste code.
  • base64QrCode — QR Code image in base64.
  • pixDueDate — PIX expiry.

Boleto-specific fields

Present in BOLETO_GENERATED and BOLETO_APPROVED:

  • barCode — barcode.
  • digitableLine — digitable line.
  • externalResourceUrl — link to access the boleto.
  • boletoDueDate — boleto due date.

The shipping object

When there is a delivery address, the payload includes the shipping object with: value, street, neighborhood, city, state, number, cep, type, complement, selectedShippingId, createdAt and updatedAt.

Tracking parameters

Cloudfy automatically captures the parameters sent in the checkout URL and forwards them in the webhook payload.

URL parameterPayload field
utm_sourceutmSource
utm_campaignutmCampaign
utm_mediumutmMedium
utm_contentutmContent
utm_termutmTerm
click_id (Kwai Ads)kwaiClickId
ttclid (TikTok Ads)tiktokClickId

xcod and subIds may also be sent.

Optional fields

The fields below are optional and may be absent, come as null or as an empty string, depending on how the checkout was accessed:

utmSource, utmCampaign, utmMedium, utmContent, utmTerm, xcod, subIds, kwaiClickId, tiktokClickId, shipping and orderPendingUrl.

Example: 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://..."
  }
}

The CHECKOUT_ABANDONED event

This event has a different payload — all fields are optional (they may come as undefined):

{
  "type": "CHECKOUT_ABANDONED",
  "payload": {
    "storeId": "66f5572e4b28b122deaa9840",
    "document": "632.444.900-93",
    "email": "joao@gmail.com",
    "fullName": "Joao Silva",
    "phone": "(11) 1 1111-1111"
  }
}
Always respond to webhooks with status 200 and handle each event idempotently — in rare cases the same event may arrive more than once.