Recipe: Individual Verification Integration

​

What you will build

1. Create a verification from your server
2. Store the returned verificationId
3. Redirect the user to the hosted link
4. Receive webhook updates
5. Mark the user as approved or rejected when a decision arrives

​

Step 1: Create the verification

curl -X POST "https://server.heliumid.io/api/v1/verifications" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "vendorData": "user_12345",
    "meta": {
      "applicationId": "app_67890"
    }
  }'

• data.verificationId
• data.link
• your own vendorData

​

Step 2: Redirect the user

​

Step 3: Listen for webhooks

• verification.successful
• verification.failed

• verification.started
• verification.processing_started

​

Step 4: Verify the signature

• Webhook-Timestamp
• Webhook-Signature
• the raw request body

​

Step 5: Update your own system

• if event === "verification.successful", mark the user as verified
• if event === "verification.failed", mark the user as rejected or request a new session

​

Minimal Node.js handler example

app.post("/webhooks/helium", express.raw({ type: "*/*" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const event = JSON.parse(rawBody);

  if (event.event === "verification.successful") {
    const { verificationId, vendorData } = event.data;
    // Mark the user as verified in your system
  }

  if (event.event === "verification.failed") {
    const { verificationId, vendorData, reason } = event.data;
    // Mark the user as rejected or request a retry
  }

  res.status(200).send("ok");
});

​

Optional polling fallback

• GET /v1/verifications
• GET /v1/verifications/{id}

​

Recommended stored fields

• verificationId
• vendorData
• current status
• latest webhook event
• raw webhook payload
• environment used