Skip to content

feat(kyc): implement async webhook callbacks for SEP-12 KYC #27

Description

@enny791

Summary

The existing SEP-12 customer information endpoint processes KYC verification synchronously. As we integrate with more advanced third-party identity providers (e.g., SumSub, Onfido), synchronous processing is no longer viable. ID verification can take several minutes, and holding the HTTP connection open leads to timeouts and poor UX.

We must pivot to an asynchronous webhook architecture. The initial PUT request should return a 202 Accepted status with a pending state. A new dedicated webhook endpoint must be exposed to receive callbacks from the ID provider. This endpoint requires rigorous HMAC signature validation to prevent spoofed approval payloads from malicious actors.

Acceptance Criteria

  • Refactor SEP-12 PUT endpoint to return 202 Accepted.
  • Create a secure /api/v1/kyc/webhook callback endpoint.
  • Implement HMAC signature verification on incoming webhook payloads.
  • Update the database state machine to transition from PENDING to APPROVED/REJECTED.

Tech Stack

TypeScript (Node.js 24), Express, Crypto (Node native). Strict security audit required.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions