Skip to main content
Webhook configurations are tied to your API key. If you switch from sandbox keys to production keys, you must re-configure your webhooks under the new key.

​
Events

  • USER_VERIFICATION_COMPLETED — the user has successfully completed verification.
  • USER_VERIFICATION_REVOKED — a previously completed verification has been revoked.
  • USER_VERIFICATION_DETERMINED_UNFULFILLABLE — the verification cannot be fulfilled.

​
Payload

{
  "transaction_id": "ewh:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_id": "bcu_123",
  "reference_user_id": "user_123",
  "type": "USER_VERIFICATION_COMPLETED",
  "payload": {},
  "created_at": "2026-02-26T20:17:13.123Z"
}

​
Signature verification

Each webhook includes an X-Hub-Signature-256 header in the format sha256=<hex>. Compute the HMAC over the raw JSON body using your webhook shared secret.
Node.js (Express)
import crypto from "crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/verifyyou",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("X-Hub-Signature-256") || "";
    const expected = "sha256=" +
      crypto.createHmac("sha256", process.env.VERIFYYOU_WEBHOOK_SECRET)
        .update(req.body)
        .digest("hex");

    if (
      !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    ) {
      return res.status(401).send("invalid signature");
    }

    const payload = JSON.parse(req.body.toString("utf8"));
    res.sendStatus(200);
  }
);

​
Retries

Failed deliveries are retried with exponential backoff, up to 16 total attempts. The backoff caps at 6 hours.

​
Admin endpoints

​
Create or edit a webhook

curl -X POST "$CONNECT_API_BASE/v1/webhook/admin/config/create_or_edit" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY" \
  -d '{
    "webhook_type": "USER_VERIFICATION_COMPLETED",
    "destination_url": "https://yourapp.com/webhooks/verifyyou"
  }'

​
List configured webhooks

curl -X POST "$CONNECT_API_BASE/v1/webhook/admin/config/get" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY"
Returns an array of configured webhooks, each with webhook_type and destination_url.

​
Delete a webhook

curl -X POST "$CONNECT_API_BASE/v1/webhook/admin/config/delete" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY" \
  -d '{
    "webhook_type": "USER_VERIFICATION_COMPLETED"
  }'

​
List recent webhook calls

curl -X POST "$CONNECT_API_BASE/v1/webhook/admin/call/get" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY"
Returns up to 50 recent webhook calls with transaction_id, webhook_type, status (PENDING, COMPLETED, or FAILED), attempts, and timestamps.

​
Rerun a webhook call

curl -X POST "$CONNECT_API_BASE/v1/webhook/admin/call/rerun" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY" \
  -d '{
    "transaction_id": "ewh:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'
The rerun creates a new webhook call with its own new transaction_id.

​
List recent webhook events

curl -X POST "$CONNECT_API_BASE/v1/webhook/admin/event/get" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY"
Returns up to 50 recent webhook call events including HTTP status, response body, and network failure information.