Skip to main content
Webhooks let the platform notify your system the moment something important happens — a checkout starts, a purchase is approved, a cart is abandoned, an order changes status, or a refund is confirmed. Think of them as push notifications for servers: instead of polling the API asking “did anything change?”, your endpoint receives the event data as soon as it happens.

​
Why use webhooks?

Without webhooks, your application would have to keep asking the API, every few seconds, “was this purchase approved yet?” — slow and inefficient. With webhooks, the platform tells you immediately, and you can:
  • update the status of an order in your system
  • fire conversion events in your tracker
  • trigger automations — emails, fulfillment, CRM
  • record financial movements
All automatically, without polling and without making anyone wait.

​
How it works

  1. You create an HTTPS endpoint in your system, e.g. https://yoursite.com/webhooks/pagamerican.
  2. You register that endpoint in Integrations > Webhooks and pick which events it should receive.
  3. When an enabled event happens, the platform sends a POST with Content-Type: application/json to your URL.
  4. Your system processes the event and responds with a success status (2xx).
One important detail: the body is always a JSON array containing a single object, not a plain object.
Your parser must expect this array and read its first (and only) element. This applies to every event, no exceptions. The registered URL is called exactly as it is — no placeholder substitution (like {some_value}) is performed.

​
Creating a webhook in the dashboard

1

Open Integrations > Webhooks

This is where you create and manage your notification endpoints. Click to create a new one.
2

Configure the endpoint

Give it a name (internal use, to tell your integrations apart) and the HTTPS URL that will receive the events.
3

Pick the events

Enable the events this endpoint should receive. Each endpoint has its own toggles, independent from the others.
4

Set the product scope and save

All products, specific products, or specific offers of a single product.
You can register as many endpoints as you need, each with its own URL, events, and product scope — for example, one endpoint just for Purchase approved of a specific product and another for all events of all products.

​
Supported events

The detailed payload of each event is documented individually in the Events section in the sidebar. Every order payload includes an isTest flag so you can tell test deliveries apart.

​
Tracking parameters

The checkout captures the query string of the link that brought the buyer. Order events return it in the trackingParameters object with a fixed set of keys: src, sck, utm_source, utm_campaign, utm_medium, utm_content, and utm_term. Keys outside this set (a custom parameter of your own, for example) are not returned. If you need an identifier of yours back in the payload, send it in src, sck, or one of the utm_* parameters.
Exception: Abandoned cart returns the full captured query string, unfiltered, in the searchParams field.

​
Amounts and commission

Every order-related event includes a commission object with the transaction amounts, always in cents:
  • totalPriceInCents — total sale amount (the ticket).
  • userCommissionInCents — net commission of whoever registered the endpoint (creator or affiliate).
  • gatewayFeeInCents — fee charged on the transaction.
  • currency — transaction currency.
Individual item prices are also in cents, in products[].priceInCents.

​
The amounts breakdown

Purchase approved, Order status updated, and Order refunded also include an amounts object with the full financial breakdown of the charge — items, coupons, shipping, tax, and the total the customer actually paid:
  • itemsGrossInCents, itemsCouponInCents, itemsNetInCents — items total, coupon discount on items, and items total after coupons.
  • shippingGrossInCents, shippingCouponInCents, shippingNetInCents — the same breakdown for shipping.
  • taxesInCents — sales tax amount.
  • totalInCents — the amount actually charged to the customer.
  • currency — transaction currency, uppercase (e.g. USD).
totalInCents is the charged amount and is not always the sum of the other fields: when the tax is inclusive, it is already embedded in the item price.Initiate checkout and Abandoned cart don’t include amounts — tax is only calculated at payment time.

​
Best practices

  • Use HTTPS on every endpoint.
  • Respond quickly with a 2xx and process the heavy work asynchronously — each delivery attempt waits at most 10 seconds.
  • Process idempotently: deliveries are at-least-once, so duplicates are possible. Use orderId + event to detect events you already handled.
  • Don’t assume ordering between events of the same order — use status and updatedAt from the payload to determine the latest state.
  • Don’t strictly validate the entire payload schema: new fields may be added over time and shouldn’t break your endpoint.
For timeouts, retries, delivery logs, and troubleshooting, see Delivery and logs.

Need help?

Our team can help you set up your integration — support@pagamerican.com