> ## Documentation Index
> Fetch the complete documentation index at: https://docs.palomma.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
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:
Unique identifier for this notification. The same `webhookId` is reused across
retries so you can deduplicate.
ISO 8601 timestamp of when this delivery attempt was made (updated on each retry).
Event type: `invoice` or `settlement`.
Event payload. The shape depends on `type` (see below).
### Event payloads
Sent when an invoice reaches its final status (`type: "invoice"`).
Unique invoice identifier.
Merchant-provided invoice reference.
One of `ready`, `paid`, `cancelled`, or `chargeback`.
Invoice amount in COP.
Invoice description.
Contract identifier.
Payment link expiration datetime (ISO 8601).
Customer's document number.
Customer's display name.
Invoice creation datetime (ISO 8601).
When the invoice was paid. Present on paid and chargeback invoices.
Payment method used. Present on paid and chargeback invoices.
One of `whatsapp`, `portal`, or `link`. Present on paid and chargeback invoices.
Amount actually paid in COP. Present on paid and chargeback invoices.
Expected settlement date. Present on paid and chargeback invoices.
Expected settlement cycle. Present on paid and chargeback invoices.
Payment identifier. Present on paid and chargeback invoices.
Palomma hosted payment page URL for this invoice.
Sent when a settlement reaches its final status (`type: "settlement"`).
Settlement date.
Settlement cycle.
One of `processing`, `paid`, `credited`, or `error`.
Number of invoices in the settlement.
Total amount collected (COP).
Fees applied (COP).
Whether fees are postpaid.
Adjustments applied (COP).
Whether the settlement went through the gateway.
Net payment amount (COP).
***
## 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)
```javascript theme={null}
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:
| Attempt | Approximate 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.