Webhooks provide a mechanism for Phaze to notify your application about transaction events in real-time, eliminating the need for polling and enabling instant user feedback. This event-driven architecture improves user experience, reduces server load, and enables automation of post-transaction workflows like balance updates, email notifications, and analytics tracking.
The webhook architecture follows industry best practices. Phaze sends HTTP POST requests to your configured endpoint URL whenever a transaction state changes. Each webhook payload contains the complete transaction object, event type, timestamp, and a cryptographic signature for verification. Your endpoint should process these events idempotently, handling duplicate deliveries gracefully.
Webhook endpoint configuration requires a publicly accessible HTTPS URL. The endpoint must respond with a 2xx status code within 10 seconds to acknowledge receipt. Phaze implements automatic retry logic for failed deliveries, with exponential backoff over 24 hours. Endpoints that consistently fail may be temporarily disabled, so implement robust error handling and monitoring.
Signature verification is critical for webhook security. Each webhook payload includes a Signature header containing a SHA256 hash of the payload body and your secret key. Your endpoint must verify this signature before processing the event, ensuring the request originated from Phaze and hasn’t been modified. The verification process mirrors API request signature generation, using the webhook payload body and your secret key.
Common webhook events cover the complete transaction lifecycle. The transaction.created event fires immediately after a purchase request is accepted, before processing begins. transaction.processing indicates the transaction is being fulfilled by the brand provider. transaction.completed signals successful completion, while transaction.failed indicates a failure that cannot be retried. transaction.refunded notifies you of refunds, whether initiated by your application or the end user.
Idempotency is essential for reliable webhook processing. Phaze may deliver the same event multiple times due to network issues or retry logic. Your endpoint should check for duplicate events using the event ID or transaction ID before processing. Implement idempotency by storing processed event IDs and checking against this store before handling new events. This prevents duplicate balance updates, email sends, or other side effects.
Error handling strategies depend on failure type. Transient errors like database unavailability should trigger retries, while permanent errors like invalid data should be logged and acknowledged. Implement exponential backoff for your own retry logic if you need to call external services. Always acknowledge webhook delivery with a 2xx status code, even if processing fails internally, to prevent Phaze from retrying unnecessarily.
Webhook endpoint security extends beyond signature verification. Implement rate limiting to prevent abuse, use HTTPS exclusively, and consider IP allowlisting if Phaze publishes webhook source IP ranges. Monitor webhook delivery patterns for anomalies that might indicate security issues. Log all webhook events for audit trails, but avoid logging sensitive data like full transaction details.
Testing webhook implementations requires simulating events. Phaze’s sandbox environment supports webhook testing, sending events for test transactions. You can also use tools like ngrok to expose local endpoints for development testing. Implement webhook replay capabilities in your testing environment to verify idempotency and error handling.
Performance optimization involves asynchronous processing. Acknowledge webhook delivery immediately with a 2xx response, then process the event asynchronously. This prevents timeouts and ensures Phaze doesn’t retry due to slow processing. Use message queues or background job processors for event handling, especially for operations that involve external API calls or database writes.
Monitoring webhook health is crucial for production reliability. Track delivery success rates, processing times, and error rates. Set up alerts for elevated failure rates or delivery delays. Phaze provides webhook delivery status in the dashboard, but you should also implement client-side monitoring. Log all webhook events with sufficient detail for debugging while maintaining security best practices.
Advanced webhook patterns include event filtering and routing. While Phaze sends all events to your configured endpoint, you can implement internal routing based on event type. For example, route transaction.completed events to your balance update service while sending transaction.failed events to your customer support system. This separation of concerns improves maintainability and scalability.
Webhook payload structure is consistent across event types. Each payload includes the event type, transaction object with full details, timestamp in ISO 8601 format, and the signature header. The transaction object contains all information needed to update your systems without additional API calls. Reference the API documentation for the complete payload schema for each event type.
Integration with existing systems requires careful design. Webhook events should trigger updates to your user balance system, transaction history, analytics pipeline, and notification services. Design these integrations to be resilient to webhook delivery delays or failures. Consider implementing reconciliation processes that periodically verify transaction states via API polling as a backup mechanism.
Best practices for webhook implementation include keeping endpoints stateless, processing events idempotently, implementing comprehensive logging, and maintaining fast response times. Design for failure scenarios: what happens if your database is down, if external services are unavailable, or if webhook delivery is delayed? Building resilience into your webhook processing ensures reliable operation even under adverse conditions.