Webhooks - PCX Developer Docs

Webhooks let PCX push event notifications to your server the moment something changes — a payment completes, a virtual account receives a deposit, or a KYB check resolves. This eliminates the need to poll for status updates.

Register your endpoint

Add your webhook URL to your organization using the Public service:

curl -X POST https://prod-api.pcxpay.com/v1/public/webhooks \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint_url": "https://yourapp.com/webhooks/pcx" }'

Your endpoint must be reachable over HTTPS. PCX starts delivering events immediately after registration. Multiple endpoints can be registered per organization.

Event payload structure

Every event follows the same envelope:

{
  "event_id": "evt_xxxx",
  "event_type": "payment.completed",
  "org_id": "org_xxxx",
  "created_at": "2025-03-16T10:00:00Z",
  "data": { ... }
}

Use event_id to deduplicate — in rare retry scenarios, PCX may deliver the same event more than once. Process each event_id exactly once.

Verify the signature

PCX signs every event with HMAC-SHA256 and sends the result in the X-PCX-Signature header. Always verify this before processing the payload.

import hmac
import hashlib

def is_valid(payload: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Reject any webhook event where the signature does not match. Never process unverified payloads — they may be spoofed.

Acknowledge receipt

Return a 2xx HTTP status within 10 seconds. PCX does not inspect the response body — any 2xx counts as a successful acknowledgement. If your processing logic takes longer than 10 seconds, acknowledge immediately and handle the event asynchronously:

@app.post("/webhooks/pcx")
async def handle_webhook(request):
    body = await request.body()
    is_valid(body, request.headers["X-PCX-Signature"], WEBHOOK_SECRET)
    background_tasks.add_task(process_event, body)
    return {"ok": True}  # Return 200 immediately

Retry schedule

Failed deliveries — non-2xx responses or connection timeouts — are retried automatically with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5+	Up to 24 hours

Events that exhaust all retries are moved to a Dead Letter Queue (DLQ). Contact support to replay DLQ events manually.

Key event types

Event	When it fires
`payment.completed`	Payment successfully delivered to beneficiary
`payment.failed`	Payment rejected or failed at the provider
`payment.processing`	Payment submitted to the provider
`virtual_account.deposit`	Funds credited to a virtual account
`virtual_account.withdrawal`	Funds debited from a virtual account
`kyb.approved`	Organization KYB verification passed
`kyb.rejected`	Organization KYB verification failed
`transaction.updated`	Transaction status changed

See Webhooks in Concepts for the full event reference, including KYC events, virtual account freeze events, and the complete data payload schema per event type.

Test your integration

Trigger a manual notification to all registered endpoints for your organization:

curl -X POST https://prod-api.pcxpay.com/v1/public/webhooks/notify \
  -H "X-Api-Key: your_api_key" \
  -H "Authorization: NONE" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_xxxx",
    "transaction_data": {
      "transaction_id": "txn_xxx",
      "status": "completed",
      "amount": 500.00,
      "currency": "USD",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  }'

Use this during development to verify your endpoint receives and processes events correctly before going live.

​Register your endpoint

​Event payload structure

​Verify the signature

​Acknowledge receipt

​Retry schedule

​Key event types

​Test your integration

Register your endpoint

Event payload structure

Verify the signature

Acknowledge receipt

Retry schedule

Key event types

Test your integration