Webhook Guide
Best Practices
Notification design guidelines, webhook integration patterns, and troubleshooting reference.
| Practice | Recommendation |
|---|
| Don't over-notify | Enable only essential notifications — excessive messages cause fatigue |
| Use thresholds | Set thresholdAmount for transaction alerts to filter micro-transaction noise |
| Channel selection | SMS for critical events (decline, block). Push for informational (success, load). |
| Template clarity | Always include card last-4, amount, balance, and timestamp in transaction notifications |
| Practice | Recommendation |
|---|
| Idempotency | Use eventTimestamp + transactionId as a deduplication key |
| Fast response | Return HTTP 200 immediately; process the payload asynchronously |
| Alerting | Monitor webhook failure rates. Alert on > 5% failure rate. |
| Logging | Log all webhook payloads for reconciliation and debugging |
| Fallback | Implement API polling as a fallback for critical events |
| Event | Priority | Reason |
|---|
KIT_STATUS_UPDATE | Must have | Track full card lifecycle |
TRANSACTION_NOTIFICATION | Must have | Real-time reconciliation |
KIT_EXPIRY_ADVANCE_NOTIFICATION | Recommended | Proactive renewal at 30/15/7 days |
KIT_INACTIVATION_ADVANCE_NOTIFICATION | Recommended | Prevent dormancy |
KIT_EXPIRY_NOTIFICATION | Optional | Post-expiry cleanup |
| Issue | Cause | Resolution |
|---|
| No notifications received | Event not enabled in product config | Check the product notification array |
| Webhook not receiving events | Subscription not created or disabled | Verify via GET /v1/event-subscriptions/ |
| Duplicate notifications | Webhook returning non-200 causing retry | Implement idempotency on your handler |
| Missing template variables | Variable not available for event type | Check the variable availability per event in the events catalog |
| SMS not delivered | DND-registered mobile number | Check DND status with your SMS gateway |
| Delayed notifications | Kafka consumer lag | Monitor Kafka consumer group lag metrics |
| Event subscription errors | Invalid destination URL | Verify HTTPS URL is publicly accessible |
| Error Code | Description | Resolution |
|---|
PP_CORP_143 | Error sending notification for entity | Check notification configuration and entity status |
PP_CORP_144 | Internal notification email not configured | Configure email in tenant settings |
When raising a notification support ticket, include:
eventType — which event is affectedentityId — customer entity IDtimestamp — approximate time of the expected notification- Subscription status — output of
GET /v1/event-subscriptions/
- Product notification config — output of
GET /v1/products/{productId}
For Kafka integration issues, also provide the consumer group ID and the topic name.
