Skip to main content
Palomma sends webhook events when something important happens. Register a URL with the Palomma team and we will send an HTTP POST with a JSON body every time an event occurs.
To enable webhooks, contact the Palomma team and provide the URL where you want to receive events.

​
When we notify

We only send webhooks on final status. Each invoice and settlement triggers a single notification. You will not receive multiple webhooks as a resource moves through intermediate states.

​
Response requirements

Your endpoint must return HTTP 200 within 5 seconds. If we don’t get a response in time, the delivery is considered failed and will be retried. We recommend acknowledging receipt immediately and processing the payload asynchronously.

​
Request structure

Every webhook is a POST request with a JSON body containing these top-level fields:
​
webhookId
string
Unique identifier for this notification. The same webhookId is reused across retries so you can deduplicate.
​
timestamp
string
ISO 8601 timestamp of when this delivery attempt was made (updated on each retry).
​
type
string
Event type: invoice or settlement.
​
data
object
Event payload. The shape depends on type (see below).

​
Event payloads

Sent when an invoice reaches its final status (type: "invoice").
​
id
string
Unique invoice identifier.
​
reference
string
Merchant-provided invoice reference.
​
status
string
One of ready, paid, cancelled, or chargeback.
​
amount
number
Invoice amount in COP.
​
description
string
Invoice description.
​
contract
string
Contract identifier.
​
expirationDate
string
Payment link expiration datetime (ISO 8601).
​
customerDocumentNumber
string
Customer’s document number.
​
customerName
string
Customer’s display name.
​
createdAt
string
Invoice creation datetime (ISO 8601).
​
paymentDate
string
When the invoice was paid. Present on paid and chargeback invoices.
​
paymentMethod
string
Payment method used. Present on paid and chargeback invoices.
​
paymentSource
string
One of whatsapp, portal, or link. Present on paid and chargeback invoices.
​
paymentAmount
number
Amount actually paid in COP. Present on paid and chargeback invoices.
​
settlementDate
string
Expected settlement date. Present on paid and chargeback invoices.
​
settlementTime
string
Expected settlement cycle. Present on paid and chargeback invoices.
​
paymentId
string
Payment identifier. Present on paid and chargeback invoices.
​
paymentUrl
string
Palomma hosted payment page URL for this invoice.

​
Verifying signatures

Every webhook includes an X-Signature header so you can confirm the request came from Palomma. The signature is an HMAC-SHA256 of the raw request body, using the integrityKey we assigned to your account.
Always verify the signature before processing the event.
To verify:
  1. Read the raw request body as a string.
  2. Compute an HMAC-SHA256 of that string using your integrityKey.
  3. Compare the result to the X-Signature header. If they match, the request is authentic.

​
Example (Node.js)

const crypto = require("crypto");

app.post("/webhooks", (req, res) => {
  const signature = req.headers["x-signature"];
  const rawBody = JSON.stringify(req.body);
  const integrityKey = process.env.PALOMMA_INTEGRITY_KEY;

  const expected = crypto
    .createHmac("sha256", integrityKey)
    .update(rawBody)
    .digest("hex");

  if (signature !== expected) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Acknowledge immediately, process later
  res.status(200).json({ ok: true });

  // TODO: handle req.body asynchronously
});

​
Retries

If a delivery fails, Palomma will retry up to 4 times. The wait between retries increases each time:
AttemptApproximate wait
1st retry~1 minute
2nd retry~5 minutes
3rd retry~25 minutes
4th retry~2 hours
The exact timing varies slightly so that retries don’t all hit your server at the same instant.

​
Handling duplicates

On retries, the webhookId stays the same but the timestamp is updated. Store the webhookId after you successfully process an event. If you receive the same webhookId again, skip it.
Make sure you do not process the same webhook more than once.