FlamPix Webhook API - Developer Documentation

Overview

A webhook is a way for FlamPix to send real-time events to your server via HTTP POST requests. Instead of polling our API to check for status changes, your server can receive a notification immediately after an event occurs.

For example, you can use webhooks to be notified when a deposit is paid, processed on the blockchain, or expired.

How it Works

Event Occurs: A deposit status changes (e.g., PIX payment received).

Notification Queued: FlamPix generates a webhook payload and adds it to a persistent delivery queue.

Delivery Attempt: Our background worker sends a POST request to your registered URL.

Verification: Your server verifies the signature to ensure the request is authentic.

Response: Your server returns a 200 OK status.

Registering a Webhook

Currently, webhook registration is managed via your account manager or through the partner management portal.

Required Configuration:

URL: The public endpoint on your server that will receive the POST requests.

Secret: You do not need to create a specific secret for your webhook; your API Secret will be used for signing. But... if you want to:

Tip: You can generate one using openssl rand -hex 32.

Request Format

All webhooks are sent as POST requests with a JSON body.

Common Headers

Header	Description
`Content-Type`	`application/json`
`X-FlamPix-Event`	The type of event (e.g., `payment_received`)
`X-FlamPix-Timestamp`	Unix timestamp in milliseconds
`X-FlamPix-Signature`	HMAC SHA-256 hex signature
`X-FlamPix-Delivery-Id`	Unique identifier for this delivery attempt
`User-Agent`	`FlamPix-Webhook/1.0`

Event Types

Event	Description
`deposit_created`	Triggered immediately after a deposit is created via API.
`payment_received`	Triggered when the PIX payment is confirmed by the bank.
`completed`	Triggered when the DePix conversion is finished and sent to the destination.
`payment_expired`	Triggered when the PIX QR code expires without payment.
`payment_cancelled`	Triggered if the transaction is manually or automatically cancelled.

Event Payloads

1. payment_received

Sent when a PIX payment is confirmed.

{
  "event": "payment_received",
  "timestamp": "2025-03-05T14:30:00.000Z",
  "data": {
    "depositId": "c2a5dbd4-043a-4d4f-866e-8ddad4ed067c",
    "status": "processing",
    "amount": {
      "grossInCents": 15000,
      "feeInCents": 575,
      "netInCents": 14425
    },
    "pix": {
      "bankTxId": "E1320335420250228200542878498597",
      "receivedAt": "2025-03-05T14:29:55.000Z",
      "payer": {
        "name": "JOÃO DA SILVA",
        "taxNumber": "12345678901",
        "bank": "001 - BANCO DO BRASIL"
      },
      "qrId": "01954e29d3337e388d5d1cb846b0d053",
      "valueInCents": 15000
    },
    "reference": "pedido_123"
  }
}

2. completed

Sent when the crypto conversion is finished.

{
  "event": "completed",
  "timestamp": "2025-03-05T14:32:00.000Z",
  "data": {
    "depositId": "c2a5dbd4-043a-4d4f-866e-8ddad4ed067c",
    "status": "completed",
    "amount": {
      "grossInCents": 15000,
      "feeInCents": 575,
      "netInCents": 14425
    },
    "completion": {
      "completedAt": "2025-03-05T14:31:50.000Z",
      "finalStatus": "depix_sent",
      "blockchain": {
        "txId": "4c7dff78eddb910b912f633d83472981fa5b8447859a7c66e49957f2a88167af",
        "network": "liquid",
        "confirmations": 2,
        "destinationAddress": "ex1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqp9lr4s",
        "depixAmount": "144.25"
      }
    },
    "reference": "pedido_123"
  }
}

Security: Verifying the Signature

To ensure the webhook was sent by FlamPix and not a third party, you must verify the X-FlamPix-Signature header.

Validation Logic

Capture the X-FlamPix-Timestamp header value.

Capture the raw request body (JSON string).

Create a "base string" by joining the timestamp, a newline character (\n), and the raw body.

Calculate the HMAC SHA-256 of the base string using your Webhook Secret.

Compare your calculated hex signature with the one in the X-FlamPix-Signature header.

Example (Node.js)

Best Practices & Handling

1. Respond Quickly

Your server should return a 200 OK status code as soon as possible (within 15 seconds). If you need to perform complex processing, do it asynchronously (e.g., using a queue) after acknowledging the webhook.

2. Handle Retries

If your server is down or returns an error (4xx or 5xx), FlamPix will retry the delivery using an exponential backoff strategy:

Attempts: Up to 5 attempts.

Intervals: 0s, 30s, 2min, 10min, 30min.

3. Idempotency

Use the depositId or X-FlamPix-Delivery-Id to detect duplicate notifications and avoid processing the same event twice.

4. Fallback Polling

While webhooks are reliable, we recommend implementing a "safety net" polling mechanism. If you haven't received a webhook for a deposit within a reasonable time (e.g., 2 hours), use the GET /deposits/{id} endpoint to check the status manually.

🪝 Webhook

FlamPix Webhook API - Developer Documentation#

Overview#

How it Works#

Registering a Webhook#

Request Format#

Common Headers#

Event Types#

Event Payloads#

1. payment_received#

2. completed#

Security: Verifying the Signature#

Validation Logic#

Example (Node.js)#

Best Practices & Handling#

1. Respond Quickly#

2. Handle Retries#

3. Idempotency#

4. Fallback Polling#