Webhooks - PCX Developer Docs

Webhooks let PCX push event notifications to your server the moment something changes — a payment settles, a virtual account receives a deposit, or a transfer completes. 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" }'

The response includes a secret_key. Store it securely — PCX uses it to sign every delivery, and it is returned only once at registration. Your endpoint must be reachable over HTTPS. PCX starts delivering events immediately after registration. By default you receive all event types. To subscribe to specific events only, pass an events array at registration or replace the list later with PUT /public/webhooks/events. Fetch the full list of subscribable types from GET /public/webhooks/events/catalogue.

Event payload structure

Every event follows the same envelope:

{
  "event_id": "9f0a1c2e-...",
  "event_type": "payment.settled",
  "event_category": "payment",
  "event_object_id": "ea5965e4-1432-40ef-bccf-cb51455a935a",
  "event_object_status": "completed",
  "occurred_at": "2026-09-04T10:00:00+00:00",
  "event_object": { ... },
  "metadata": { ... }
}

event_object carries the object the event is about; event_object_id and event_object_status lift its identifier and status to the envelope.
occurred_at is when the event happened; a timestamp field records when the delivery was sent.
A legacy data field duplicates event_object for existing integrations.

Use event_id to deduplicate — it stays the same across retries, and PCX may deliver the same event more than once. Process each event_id exactly once.

Verify the signature

PCX signs every delivery with HMAC-SHA256 using your secret_key. Two signature headers are sent:

Header	Contents
`X-Webhook-Signature`	`sha256=` + HMAC-SHA256 of the raw request body
`X-Webhook-Signature-V2`	`sha256=` + HMAC-SHA256 of `<timestamp>.<raw body>`, where `<timestamp>` is the value of `X-Webhook-Timestamp` (Unix seconds)

Deliveries also include X-Event-Type and X-Event-ID headers. Prefer the v2 signature — including the timestamp protects against replay. The timestamp is set per delivery attempt, so also reject timestamps older than a window you choose (for example five minutes). Always compute the HMAC over the exact raw bytes of the request body — do not re-serialize the parsed JSON.

import hmac
import hashlib

def is_valid_v2(raw_body: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    message = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), message, 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 30 seconds (the default delivery timeout). PCX does not inspect the response body — any 2xx counts as a successful acknowledgement. If your processing logic takes longer, acknowledge immediately and handle the event asynchronously:

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

Retry schedule

PCX attempts delivery up to 3 times in quick succession. If all fail, the event is retried on a backoff schedule:

Retry	Delay after previous attempt
1	1 minute
2	5 minutes
3	15 minutes
4	1 hour
5	6 hours
6	24 hours
7	48 hours

Events still failing after 11 total attempts are marked permanently failed. Contact support to redeliver a permanently failed event.

Event types

Event	When it fires
`payment.initiated`	Payment created and accepted for processing
`payment.settled`	Payment successfully settled to the beneficiary
`payment.failed`	Payment rejected or failed at the provider
`virtual_account.created`	Virtual account provisioned
`virtual_account.deposit_received`	Funds credited to a virtual account
`virtual_account.transfer_initiated`	Transfer from a virtual account started
`virtual_account.transfer_completed`	Transfer from a virtual account completed
`virtual_account.transfer_failed`	Transfer from a virtual account failed
`virtual_account.transfer_refunded`	Transfer refunded to the virtual account
`virtual_account.transfer_cancelled`	Transfer cancelled before completion

See Webhooks in Concepts for the payment event payload schema.

Test your integration

Fire a synthetic event at your registered endpoint — signed with your real secret — to verify signature validation and processing end to end:

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

event_type defaults to virtual_account.deposit_received when omitted. The response reports whether your endpoint acknowledged the delivery.

​Register your endpoint

​Event payload structure

​Verify the signature

​Acknowledge receipt

​Retry schedule

​Event types

​Test your integration

Register your endpoint

Event payload structure

Verify the signature

Acknowledge receipt

Retry schedule

Event types

Test your integration