KYC Webhook Verification Record
A nine-field verification record with blank PDF/CSV downloads and fictional V-01/V-02 examples. Capture the authentication decision before application-state changes.
Purpose and scope
Use this KYC webhook verification template to record whether an incoming delivery passed the configured authentication checks before changing application state. Copy the nine fields, preserve a restricted evidence reference and name the owner of any unresolved verification question.
The form contains no signing secrets or applicant data. All V-01/V-02 values below are fictional. This record supports an engineering review; it is not a KYC decision or a compliance certification.
Blank working record
Copy the fields into your evidence system or use the downloads above. Replace each blank with a value or an explicit unresolved question. Do not place raw payloads or signing secrets in this form.
| Field | Your value | What to record |
|---|---|---|
| delivery_ref | ________________ | Internal delivery reference. Use a synthetic or access-controlled reference, not an applicant identity. |
| provider_doc_version | ________________ | Provider, documentation URL, revision if supplied and access date. If no revision is shown, say so. |
| body_capture_method | ________________ | Where original HTTP body bytes are captured before parsing or other transformation. |
| signature_scheme | ________________ | Expected algorithm, signed material, header format and encoding from the selected provider contract. |
| key_identifier_only | ________________ | Non-secret internal key label or version only. Do not copy the signing secret. |
| verification_result | ________________ | PASS, FAIL or NOT_VERIFIED with a reason and the checks actually completed. |
| rejection_route | ________________ | Named handler for failure or missing evidence; state whether application state remains unchanged. |
| redacted_evidence_ref | ________________ | Access-controlled reference to redacted evidence. Do not paste payloads or identity documents. |
| owner | ________________ | Role accountable for the verification decision and unresolved configuration questions. |
Fictional example: V-01 and V-02
A local demonstration signs one synthetic JSON body, then checks the original signature against the original and compactly reserialized bytes. The JSON meaning is unchanged; the byte sequence differs. V-01 matches. V-02 does not. These are local fixture results, not Sumsub deliveries.
| Field | V-01: original bytes | V-02: reserialized bytes |
|---|---|---|
| delivery_ref | V-01 | V-02 |
| provider_doc_version | Sumsub webhook-manager; accessed 2026-10-27; revision not exposed | Sumsub webhook-manager; accessed 2026-10-27; revision not exposed |
| body_capture_method | Original synthetic HTTP body bytes before JSON parsing | Parsed and compactly reserialized JSON; intentional negative fixture |
| signature_scheme | HMAC_SHA256_HEX; hex digest over body bytes; local fixture only | HMAC_SHA256_HEX; hex digest over body bytes; local fixture only |
| key_identifier_only | fixture-key-01 (internal label, not a provider header) | fixture-key-01 (internal label, not a provider header) |
| verification_result | PASS_LOCAL_FIXTURE: digest matches original bytes | FAIL_BODY_CHANGED: digest does not match original signature |
| rejection_route | Continue to separate schema, duplicate and state-transition checks; no applicant decision | Reject authentication; application state unchanged; use documented response policy |
| redacted_evidence_ref | fixture/V-01/original-bytes (synthetic local reference) | fixture/V-02/changed-bytes (synthetic local reference) |
| owner | Integration engineering (fictional role) | Integration engineering (fictional role) |
The sample key label is internal to the demonstration. No provider key or real applicant identifier appears in the records. A successful authentication result still needs the independent checks described below.
What each decision field means
Complete one record for each delivery under investigation. A delivery reference identifies a receipt attempt; a provider event reference may identify the underlying event. Keep that distinction in the restricted evidence system. An applicant reference belongs there only when necessary and appropriately protected. The public form needs neither an applicant name nor a real applicant ID.
For provider_doc_version, save the source URL and access date alongside an actual revision when one is available. An access date is not a provider release number. Preserve a restricted snapshot or document hash in the linked evidence if your review process requires reproducibility.
body_capture_method should identify the capture boundary. A field reading "JSON received" does not tell a reviewer whether middleware changed the bytes. Record whether capture occurred before a parser, decoder or other transformation. Keep any real request body in an approved restricted system, never in this downloadable record.
Choose the expected signature scheme
The Sumsub webhook manager documentation describes x-payload-digest and x-payload-digest-alg, with HMAC calculated over the unaltered body bytes. Match the declared algorithm to the expected configuration; do not treat an arbitrary incoming algorithm as permission to select any verifier. Record the header format and digest encoding as part of signature_scheme.
Sumsub currently documents SHA256 as the dashboard default and notes that some older configurations can use SHA1. Confirm the actual webhook configuration rather than copying a default from this example. The fixture uses HMAC_SHA256_HEX only to demonstrate byte preservation.
Record a key label without exposing the key
key_identifier_only is an internal reference such as an approved secret version. It is not the signing secret and need not be a header supplied by the provider. During webhook signing-key rotation, record the version actually used and refer to the approved transition configuration. This template does not assume that Sumsub sends a key identifier or simultaneous signatures.
Use your provider's supported rotation process. If the key version cannot be resolved, mark NOT_VERIFIED and assign the configuration question to the owner. Do not turn a missing key into a successful result.
Make rejection an explicit route
verification_result records only what was checked. Use PASS only after the expected verification succeeds. FAIL includes a reason such as a missing signature, a malformed digest or a mismatch. NOT_VERIFIED means verification could not be completed. Neither failure state authorizes an applicant-state change.
rejection_route names the handler and evidence owner. Define the actual response code against the provider's current delivery policy. Sumsub currently treats HTTP 401, 403 and 404 as permanent delivery failures, so a rejection response can also change retry behavior. Do not copy a response code without reviewing that consequence.
redacted_evidence_ref should resolve for an authorized reviewer while revealing no credential or applicant information in the record itself. owner names an accountable role; it is not a substitute for the evidence. If a required field is unknown, hold the trust decision and record the question.
Verification limits and implementation checks
The OWASP Webhook Security Cheat Sheet recommends the provider's exact verification format, constant-time digest comparison and restricted handling of signing secrets. Follow the selected protocol rather than adding assumptions about signed timestamps or identifiers.
A matching signature does not establish event freshness, prevent repeated processing or determine whether a KYC applicant should be approved. Schema validation, duplicate handling and permitted state transitions remain separate gates. Where a provider does not authenticate a timestamp or event ID, an unsigned header does not become trustworthy because this form has been filled in.
- Capture a sanitized fixture through the same ingress path as the intended endpoint.
- Check original bytes, altered bytes and missing or unsupported signature data. Keep expected and observed outcomes separate.
- Confirm that failed verification leaves application state unchanged and follows the documented rejection route.
- Attach the resulting restricted evidence reference and accountable owner before accepting the integration behavior.
These are proposed implementation checks. The local V-01/V-02 exercise checks a synthetic HMAC calculation only. No provider delivery, production endpoint, applicant decision or client security test was executed.
Use the record in an integration brief
For a blockchain application that consumes KYC callbacks, discuss this authentication boundary with Pharos Production as part of blockchain integration development services. Attach the record to the implementation brief so the team can agree the capture point and the failure behavior before application-state changes are allowed.
The Blockchain Integration Readiness Worksheet provides the broader readiness context. Use this narrower record for the delivery-verification evidence it does not capture.
Sources and document scope
- Sumsub Webhooks: product scope and delivery channels.
- Sumsub Webhook manager: sender verification, configuration and delivery-response behavior.
- OWASP Webhook Security Cheat Sheet: general authentication and endpoint controls.
Sources checked October 27, 2026. Provider documentation can change. No immutable provider revision was exposed in the reviewed page; retain the exact version used for your integration. Resource version 1.0.