Question 1

How do I set up a webhook?

Accepted Answer

Under Webhooks, click Add webhook and enter your system's URL. Cloudfy then sends checkout events (in real time) to that URL, enabling custom automations and access provisioning.

Question 2

My webhook isn't firing. What should I check?

Accepted Answer

If events do not reach your system, the problem is usually in the URL or the destination server.Most common causesIncorrect or unreachable URLDestination server returning an errorEvent not configuredResponse timeoutVerification checklistConfirm the URL registered under Webhooks.Test the URL manually (Postman, cURL, webhook.cool or RequestBin).Make sure the destination accepts POST requests and is online.Check that the desired event is enabled.If the URL is correct but returns a 500 error, the problem is on the destination server. If it persists, contact support.

Question 3

How do I integrate with Utmify?

Accepted Answer

The Utmify integration sends your orders for conversion tracking and attribution. The process takes just a few minutes.1. Start the integration in CloudfyIn Cloudfy, go to Integrations, find Utmify and click Integrate. An API Token will be requested.2. Generate the API Token in UtmifyIn Utmify, go to Integrations › Webhooks › API credentials and click Add credential. Fill in any name you like, click Create credential and copy the generated API Token.3. Paste and validate in CloudfyGo back to Cloudfy, paste the token into the API Token field and validate it to confirm it is the right credential.4. Select the eventsCheck all order status options:Pending orderPaid orderRefunded order or chargebackDeclined order5. Save and finishClick Save in Cloudfy — a notice will confirm the integration was set up successfully. Finally, return to Utmify and click Finish.Keep the API Token secret. If you have questions about the integration, contact Utmify support or our support.

Question 4

I want to integrate a website or link, how do I do it?

Accepted Answer

You can send the customer to a website or link (members area, group, form, etc.) using Cloudfy's approved-order email with a custom button.1. Create the digital productIn Products › Create product, create a digital product and attach any deliverable (it can be a simple file).2. Create the email templateGo to Recovery › Templates › Create template. Open another tab and ask the AI of your choice to generate an HTML email template (approved), with a button that sends to your preferred link.If you want to use the order data in the email, ask the AI to include these checkout parameters:{{nome}}{{email}}{{telefone}}{{id}}{{total}}{{linkDoPedido}}{{downloadLink}}{{items[].nome}}3. Paste the template in CloudfyCopy the HTML the AI generated, go back to Cloudfy and paste it into Template editor. At the top, under Email type, select Approved order, give the template a name and save.4. Enable the template for approved ordersGo to Recovery › Settings, find Approved order, click Default approved-order email and switch it to the template you just created.5. Check the email domainFinally, check that your email has an approved domain so we can send the approved-order email. If it isn't, see how email delivery works:Info-product deliveryThe email button can point to any URL — members area, WhatsApp/Telegram group, form or another site.

Question 5

Webhooks documentation: events and payloads

Accepted Answer

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 formatEvery event arrives with two top-level fields: type (the event name) and payload (the order data).{   "type": "PIX_APPROVED",   "payload": { ... } }Available eventsEvent (type)When it firesPIX_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 fieldsPresent 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 fieldsPresent in BOLETO_GENERATED and BOLETO_APPROVED:barCode — barcode.digitableLine — digitable line.externalResourceUrl — link to access the boleto.boletoDueDate — boleto due date.The shipping objectWhen 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 parametersCloudfy automatically captures the parameters sent in the checkout URL and forwards them in the webhook payload.URL parameterPayload fieldutm_sourceutmSourceutm_campaignutmCampaignutm_mediumutmMediumutm_contentutmContentutm_termutmTermclick_id (Kwai Ads)kwaiClickIdttclid (TikTok Ads)tiktokClickIdxcod and subIds may also be sent.Optional fieldsThe 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 eventThis 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.

Articles about integrations & webhooks

How do I set up a webhook?

My webhook isn't firing. What should I check?

How do I integrate with Utmify?

I want to integrate a website or link, how do I do it?

Webhooks documentation: events and payloads