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:

string

Unique identifier for this notification. The same webhookId is reused across retries so you can deduplicate.

string

ISO 8601 timestamp of when this delivery attempt was made (updated on each retry).

string

Event type: invoice or settlement.

object

Event payload. The shape depends on type (see below).

Event payloads

Invoice
Settlement

Sent when an invoice reaches its final status (type: "invoice").

string

Unique invoice identifier.

string

Merchant-provided invoice reference.

string

One of ready, paid, cancelled, or chargeback.

number

Invoice amount in COP.

string

Invoice description.

string

Contract identifier.

string

Payment link expiration datetime (ISO 8601).

string

Customer’s document number.

string

Customer’s display name.

string

Invoice creation datetime (ISO 8601).

string

When the invoice was paid. Present on paid and chargeback invoices.

string

Payment method used. Present on paid and chargeback invoices.

string

One of whatsapp, portal, or link. Present on paid and chargeback invoices.

number

Amount actually paid in COP. Present on paid and chargeback invoices.

string

Expected settlement date. Present on paid and chargeback invoices.

string

Expected settlement cycle. Present on paid and chargeback invoices.

string

Payment identifier. Present on paid and chargeback invoices.

string

Palomma hosted payment page URL for this invoice.

Sent when a settlement reaches its final status (type: "settlement").

string

Settlement date.

string

Settlement cycle.

string

One of processing, paid, credited, or error.

number

Number of invoices in the settlement.

number

Total amount collected (COP).

number

Fees applied (COP).

boolean

Whether fees are postpaid.

number

Adjustments applied (COP).

boolean

Whether the settlement went through the gateway.

number

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:

Read the raw request body as a string.
Compute an HMAC-SHA256 of that string using your integrityKey.
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:

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.

Introduction

API Documentation

Webhooks

When we notify

Response requirements

Request structure

Event payloads

Verifying signatures

Example (Node.js)

Retries

Handling duplicates

​When we notify

​Response requirements

​Request structure

​Event payloads

​Verifying signatures

​Example (Node.js)

​Retries

​Handling duplicates

When we notify

Response requirements

Request structure

Event payloads

Verifying signatures

Example (Node.js)

Retries

Handling duplicates