Webhook event type
TRANSACTION_STATUS_CHANGED
Version 2.0.0 event sent when a transaction reachesCOMPLETED, FAILED, or DECLINED. The current transaction is available in data.transaction, and eventId identifies the webhook delivery.
Retries and delivery behavior
PrimeVault sends each webhook as an HTTPPOST request with a JSON body. Return a 2xx response as soon as the event has been accepted, then perform longer processing asynchronously.
- Request timeout — 30 seconds per attempt. If the endpoint does not respond in time, the attempt fails.
- Attempts — Up to 4 total: one initial attempt plus up to three retries.
- Backoff — 2 seconds before the second attempt, 4 seconds before the third, and 8 seconds before the fourth.
- Retry conditions — Network errors, timeouts, and HTTP
4xxor5xxresponses are retried. - After final failure — Delivery stops after the fourth failed attempt. Reconcile transaction status through the Transactions API if delivery is missed.
Handling recommendations
Retries can produce duplicate deliveries, for example, when your endpoint processes a request but its response is lost. Make webhook handling idempotent and deduplicate usingeventId.
Verify webhook signatures
Each delivery includesX-Signature and X-Timestamp headers. Use the verification key for the configured endpoint to verify the event before accepting or processing it.
Compute HMAC-SHA256 over the canonical JSON body followed immediately by the X-Timestamp header value, with no separator. Canonical JSON sorts object keys, removes insignificant whitespace, and preserves Unicode characters. Compare the lowercase hexadecimal digest with X-Signature using a constant-time comparison.
Reject missing or invalid signatures. Apply a timestamp tolerance appropriate for your receiver; the example below uses five minutes. Keep the receiver clock synchronized. PrimeVault generates a fresh timestamp and signature for each retry.
verify_webhook.py
X-Timestamp and X-Signature header values into verify_webhook. Read missing headers as empty strings. Keep the endpoint verification key in your secret store. A valid signature authenticates the event; your handler must still validate the event version, type, and payload before applying changes.
After verification, durably record or enqueue the event and return 2xx promptly. Deduplicate retries by eventId. Make business updates idempotent by transaction ID and status as well, because a separate notification about the same transaction can have a new eventId. Use the Transactions API to reconcile current status.