Webhook Setup

How Webhooks Work

When a Pix payment is received on one of your keys, the PSP can notify your application in real-time via an HTTP POST request. This is essential for:

• Confirming payments in e-commerce
• Updating order status
• Sending receipts
• Triggering automated workflows

The Efí Webhook Flow

1. You register a webhook URL for a Pix key
2. Customer makes a Pix payment to that key
3. Efí sends POST to your_url/pix with payment details
4. Your server responds 200 OK
5. If no 200, Efí retries (up to 3 times)

Register a Webhook

pixcli webhook register --key "+5511999999999" --url "https://example.com/webhook"

Verify Registration

pixcli webhook get --key "+5511999999999"

Remove a Webhook

pixcli webhook remove --key "+5511999999999"

mTLS Requirement

Production

In production, Efí requires mutual TLS (mTLS) for webhook endpoints. This means:

1. Your server must present a valid TLS certificate
2. Your server must also validate Efí's client certificate
3. Efí provides their CA certificate for this purpose

You need to configure your reverse proxy (nginx, Caddy, etc.) to require client certificates signed by Efí's CA.

Sandbox

In sandbox mode, mTLS is not enforced. Any HTTPS endpoint works, making development much simpler.

Local Development

For local development, use the built-in webhook listener:

pixcli webhook listen --port 8080

Combined with a tunnel service like ngrok:

# Terminal 1: Start the listener
pixcli webhook listen --port 8080

# Terminal 2: Expose via ngrok
ngrok http 8080

# Terminal 3: Register the ngrok URL
pixcli --sandbox webhook register \
  --key "+5511999999999" \
  --url "https://abc123.ngrok-free.app/webhook"

Next Steps

• Deploy webhook server for production
• Webhook events reference for payload formats