Generic Webhook
Generic Webhook is HyperVerge's centralized system for delivering event notifications (webhooks) to client servers. When something happens in a KYC flow — a transaction completes, a reviewer makes a decision, a user opens a link — the client's server needs to know. Generic Webhook is the system that sends that notification reliably.
Why?
Instead of each product building its own webhook-sending logic, they all plug into this one system. It handles delivery, retries, signing, routing, and logging centrally.
What does this guide cover?
- System Architecture: How the Configuration API and Delivery Service work together to manage and deliver webhooks.
- Event Producers: How different producers like Audit Portal, Link KYC plug into the system and what events they send.
- Webhook Delivery: How events flow from S3 through SQS to the Lambda-based Delivery Service, which fetches configs, signs payloads, and delivers webhooks.
- Security: HMAC-SHA256 signature generation and how to verify webhooks are genuinely from HyperVerge.
- Monitoring & Debugging: Redshift-based delivery metrics, failure tracking, and troubleshooting common issues.
Who is this guide for?
This documentation is intended for:
- Developers building or maintaining the Generic Webhook system.
- Solutions/Support Team setting up webhook delivery for a new client.
- Anyone who wants to understand how the Generic Webhook system works end to end.
When should this be used?
- New Webhook Setup: When configuring a new appId/eventType for webhook delivery.
- Debugging Delivery Issues: When webhooks are not being delivered or are failing.
- Client Integration: When a client needs to understand the webhook payload format and how to verify signatures.
- Operations: When monitoring delivery health or investigating failures.
Prerequisites
- Knowledge of AWS services (Lambda, SQS, S3, DynamoDB)
- Understanding of HTTP webhooks and HMAC signature authentication
- Familiarity with Node.js
Deep dive
- Generic Webhook - Architecture — What it is, the Configuration API vs Delivery Service, DynamoDB schema, and repo paths.
- Generic Webhook - Flow — End-to-end delivery flow (S3 → SQS → Lambda), event producers, HMAC, and routing.
- Generic Webhook - Integration Guide — SE/IE-facing guide: Config API URLs, setting up clients, and troubleshooting.
- Generic Webhook - Engineering — Dev-facing: architecture deep dive, codebase, Redshift schemas, env vars, and alerts.
- Generic Webhook - API Reference — POST/GET/PATCH Config API reference with curl examples.
note
This documentation is a work in progress. If something is missing or unclear, please suggest improvements via the Notion Suggestion/Improvements/Fixes page.