pixcli webhook

Commands

`pixcli webhook register`

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

Output:

✅ Webhook registered
   Key: +5511999999999
   URL: https://example.com/webhook/pix

Efí appends /pix to your webhook URL automatically. If you register https://example.com/webhook, notifications will be sent to https://example.com/webhook/pix.

Flags

Flag	Required	Description
`--key`	Yes	Pix key to associate with the webhook
`--url`	Yes	Webhook URL (Efí appends `/pix` to this)

`pixcli webhook get`

Get the registered webhook for a Pix key.

pixcli webhook get --key "+5511999999999"

Output:

🔔 Webhook
   Key: +5511999999999
   URL: https://example.com/webhook
   Created: 2026-03-19T10:00:00Z

`pixcli webhook remove`

Remove the webhook for a Pix key.

pixcli webhook remove --key "+5511999999999"

Output:

✅ Webhook removed for key: +5511999999999

`pixcli webhook listen`

Start a local webhook listener server. This is useful for development and testing.

pixcli webhook listen --port 8080

Output:

🔔 Webhook listener started on http://0.0.0.0:8080
   Endpoints:
     POST /pix    — receive Pix notifications
     GET  /health — health check

   Waiting for events... (Ctrl+C to stop)

Flags

Flag	Required	Default	Description
`--port`	No	`8080`	Port to listen on
`--forward`	No	—	Forward received events to this URL via POST
`--output`	No	—	Append events to this file (JSONL format)

Forward to another service

pixcli webhook listen --port 8080 --forward "http://localhost:3000/api/pix"

Save events to a file

pixcli webhook listen --port 8080 --output events.jsonl

Forward and save simultaneously

pixcli webhook listen \
  --port 8080 \
  --forward "https://hooks.slack.com/services/T00/B00/xxx" \
  --output events.jsonl

How Efí Webhooks Work

You register a webhook URL for a Pix key
When a Pix payment is received on that key, Efí sends a POST request to your URL
The request contains the payment details (E2E ID, amount, payer info)
Your server responds with 200 OK to acknowledge

mTLS Requirement

In production, Efí requires mutual TLS (mTLS) for webhook endpoints. Your server must present Efí's CA certificate to establish the connection.

In sandbox, mTLS is not enforced — any HTTPS endpoint works.

See Webhook Deployment for production setup instructions.

The `/pix` Suffix

Efí automatically appends /pix to your registered webhook URL. This is a quirk of the Efí API:

You register: https://example.com/webhook
Efí sends to: https://example.com/webhook/pix

The pixcli webhook listen server already handles this by listening on the /pix endpoint.

pixcli webhook

On this page