Webhook Signature Verification: Securing KYC Callbacks Against Spoofing
A POST request is not proof of origin. Here's how to verify KYC webhook signatures, block replay attacks, and reconcile against the authoritative record.
This article reflects the public VOVE ID webhook documentation available on that date and is not legal advice.
Verify every KYC webhook before acting on it: preserve the received payload as required by the provider's verification process, validate the signature with the configured secret, check the timestamp and event identity, then retrieve or reconcile the authoritative verification record before granting an outcome.
VOVE ID helps product, risk, and engineering teams use KYC status changes inside an accountable onboarding workflow. The weak point is often not document capture. It is the callback handler that treats any HTTP request as permission to change an applicant's status.
This is exactly where teams lose control over risk.
This is a security deep-dive on the webhook channel itself. For the broader question of when to use webhooks versus polling in the first place, see our Webhooks vs Polling guide.
The callback boundary: a POST is not proof of origin
A webhook is a delivery mechanism. It tells a receiving endpoint that an external event occurred, but the receiver still needs to establish that the message came from the expected sender and has not been altered or reused.
Transport security matters, but TLS alone does not make a received event a valid business instruction. OWASP recommends TLS for sensitive web-service communication and distinguishes message integrity from transport confidentiality. OWASP's Web Service Security Cheat Sheet is a useful baseline for the boundary.
VOVE ID's public webhook documentation lists Svix-Id, Svix-Signature, and Svix-Timestamp headers, and says the dashboard generates a unique secret when a webhook URL is configured. Verify the current provider instructions before writing the handler; do not assume an algorithm from header names alone. Read the current VOVE ID webhook documentation.
The safe sequence: validate before the state change
The handler should receive the event, verify it according to the provider's documented process, and only then allow downstream processing. Do not let an unverified payload directly approve an account, create a payout entitlement, or close a compliance case.
Timestamp handling matters because a valid delivery can still be replayed. Treat the timestamp and event identifier as controls that need an explicit policy: a bounded acceptance window, duplicate detection, and a record of already processed events. Define the policy for your product and confirm its compatibility with the provider's documentation.
After verification, reconcile the event with the authoritative verification record using the product's reference identifier. VOVE ID's retrieval documentation describes using refId after a webhook notification to retrieve a user verification. That is a useful separation: the event triggers work; the verified record informs the decision. See the documented verification retrieval flow.
For the underlying KYC control framework, see our KYC requirements article.
A realistic failure: a forged success event reaches production
A marketplace receives KYC callbacks at a public endpoint.
The team has:
- an endpoint that parses JSON immediately
- application code that reads status
- a rule that activates the seller when status says successful
Then an attacker sends a crafted request to that endpoint with the same field. The handler has no verified signature check and no event-identity record, so it creates the same state change as a genuine callback.
The onboarding record now looks complete, while the actual verification system has no matching successful result.
This is not a KYC decision failure. It is an untrusted-ingress failure.
The implementation pattern: keep raw receipt, verification, and decision separate
The exact framework code varies, but the operating sequence should stay visible. First, capture the received request in the form required for signature verification. Next, verify it with the current secret and provider procedure. Then apply timestamp and duplicate-event checks. Finally, put the event into a controlled processing path that retrieves or reconciles the verification record before changing the product state.
This means one thing: webhook verification belongs at the ingress boundary, before parsing convenience or business logic turns an external message into an internal instruction.
How VOVE ID fits: use the event to start reconciliation
VOVE ID's documented webhook payload uses refId as the current identifier and notes that userId remains only for backward compatibility. Build new workflows around the current documented identifier, then use the documented retrieval endpoint when the product needs the verification detail.
The public documentation also describes retry behavior for failed webhook delivery. That makes duplicate handling an operational requirement for the receiving service, even when delivery is legitimate. Keep a durable processed-event record and make downstream state changes safe to retry.
Practical webhook verification checklist
Ingress
- Enforce HTTPS and restrict the endpoint to the webhook purpose.
- Preserve the request representation required by the provider's verification method.
- Reject requests that fail the documented signature verification process.
Freshness and duplicates
- Define and enforce a timestamp acceptance window.
- Store the received event identifier before downstream processing.
- Prevent the same verified event from creating the same state change twice.
Decisioning
- Map the verified event to the internal applicant through the current reference identifier.
- Retrieve or reconcile the authoritative verification record before approval.
- Send exceptions and mismatches to a defined review path.
Operations
- Keep webhook secrets out of source control and rotate them through a controlled procedure.
- Log verification outcomes without storing unnecessary sensitive payload data.
- Test forged, stale, duplicate, and out-of-order event scenarios before launch.
FAQ
Does HTTPS remove the need to verify a webhook signature?
No. HTTPS protects the transport connection, but the receiver still needs the provider's documented mechanism to authenticate the message and protect the business workflow from spoofed requests.
Should the handler parse JSON before signature verification?
Follow the provider's documented verification method. If it requires the received body in a particular form, preserve that form until the verification step completes.
Can a verified webhook approve an applicant by itself?
It should trigger the controlled verification workflow. Retrieve or reconcile the authoritative result before the product grants an approval state.
Which headers should a VOVE ID webhook handler expect?
The public documentation lists Svix-Id, Svix-Signature, and Svix-Timestamp. Check the live documentation before implementation because header and verification details can change.
What should happen when verification fails?
Return an appropriate error response, log the reason safely, and do not advance the applicant. Do not expose the secret, signature material, or sensitive payload data in customer-facing errors.
Conclusion
Webhook security is not a signature check added after onboarding. It is the boundary that decides whether an external callback can become an internal compliance action.
Teams should separate receipt, verification, replay handling, reconciliation, and decisioning. That gives product and compliance teams an event trail they can explain when the result matters.
Want to see how VOVE ID can fit trustworthy callback handling into your identity and compliance workflow?
This article is intended for general informational purposes only and does not constitute legal, financial, or regulatory advice. KYC/KYB/AML requirements may vary depending on jurisdiction, industry, and specific business circumstances. For up-to-date and binding compliance obligations, readers should refer to the relevant regulatory authorities or consult qualified professionals.
