Webhooks

Build withCopy prompt

Webhooks let you receive verification outcomes (and other events) in real time instead of polling. Myaza sends a signed HTTP POST to each endpoint you register whenever a subscribed event occurs.

Register and manage endpoints under Settings → Organization → Developers → Webhooks. Endpoints are environment-scoped; test your integration with sandbox endpoints before enabling production.

Request format

Build withCopy prompt

Each delivery is a POST with a JSON body and these headers:

Event types

Build withCopy prompt

The data payloads for the compliance events (entity.created, identity.resolved, event.flagged, screening.match, alert.*) are documented with each feature. See Identity Hub API and Event monitoring. The workflow.* events are documented under Decisioning.

Payload structure

Build withCopy prompt

All events share the same envelope; the data object varies by event type.

{
  "id": "evt_01j9abc123",
  "event": "verification.completed",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "data": {
    "verificationId": "ver_01j9xyz456",
    "requestId": "order_1001",
    "externalId": "prov_rec_01j9",
    "externalUserId": "user_42",
    "metadata": { "loanId": "loan_20191" },
    "workflowId": "wf_AbC123dEf456",
    "workflowVersion": 3,
    "status": "approved",
    "checkStatus": "verified",
    "reason": null,
    "reasonCode": null,
    "idType": "bvn",
    "country": "NG",
    "idNumber": "12345678901",
    "userData": {
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfBirth": "1990-01-01"
    },
    "facialMatch": { "match": true, "confidence": 85 },
    "media": {
      "selfie": "https://trust.myaza.app/api/kyc/verifications/ver_01j9xyz456/media/selfie",
      "livenessVideo": "https://trust.myaza.app/api/kyc/verifications/ver_01j9xyz456/media/liveness-video"
    },
    "environment": "PRODUCTION",
    "createdAt": "2026-04-27T12:00:00.000Z"
  }
}

On a non-success event (verification.failed, .not_found, .error) the data carries a human-readable reason and a stable reasonCode you can branch on; both null above:

{
  "status": "declined",
  "checkStatus": "failed",
  "reason": "The document expired on 2020-01-01. A current, non-expired document is required.",
  "reasonCode": "document_expired"
}

See the full failure reason codes catalogue.

workflowId is the workflow that drove the verification (null for SDK mounts configured with plain props). When the workflow has a decision graph, the pass/fail result above arrives first, and the approve / decline / review decision follows in a separate workflow.run.completed event.

workflowVersion is the published version that actually ran. Publishing a workflow overwrites its live config in place and bumps the version, so the id alone stops describing what happened as soon as you publish again; store the pair. Look up the exact configuration a version used in the dashboard under Workflows → Version history. It is null when the verification had no workflow, predates this field, or attributed to a workflow that was never published.

An api_key.* event's data instead looks like:

{
  "id": "evt_01j9abc789",
  "event": "api_key.created",
  "createdAt": "2026-04-27T12:00:00.000Z",
  "data": {
    "apiKeyId": "key_01j9abc000",
    "name": "Mobile app production key",
    "environment": "PRODUCTION",
    "createdBy": "user@example.com"
  }
}

Your reference on every event

Build withCopy prompt

You never need a mapping table to know which of your users an event is about. Every event that originates from an entity, a session or a verification carries two fields beside Myaza's own ids:

Myaza's ids (verificationId, entityId, sessionId, alertId, ...) stay exactly where they are; the two fields are added, never substituted. Both are resolved once, when the event is created, and persisted with it, so a retry or a manual redelivery replays the same values even if you later changed the entity. externalId on verification events is the verification source's own record id, kept for compatibility; correlate on externalUserId.

Events about your organisation rather than one of your users carry neither field: api_key.*, credits.low, credits.topped_up, credits.granted, credits.promo_expired and screening.adjudication_overdue. A KYB key person's own verification events resolve to the business's reference (the applicant you know), while events about that person's entity keep the kp_ id you received in keyPeopleInvites.

Status and checkStatus

Build withCopy prompt

Every verification payload carries two status fields, and the difference between them matters.

status is what happened. It is the single value to drive your own record off, and it is the same vocabulary the dashboard shows and GET /api/kyc/status/:id returns, so polling and listening can never disagree.

checkStatus is what the checks found: pending, verified, failed, not_found or error. It never moves once the checks finish, whatever anybody decides afterwards.

Why both

The two are usually the same thing said twice. They come apart exactly when a person overrides the automated result, and that is the case worth being able to see.

Take an applicant whose selfie scored just under the pass mark. The checks fail. Your workflow routes it to review rather than declining outright, a compliance officer looks at the photos, recognises a lighting problem rather than a different face, and approves.

That verification is now:

{
  "status": "approved",
  "checkStatus": "failed",
  "reasonCode": "selfie_mismatch",
  "decision": "APPROVED",
  "reviewedById": "usr_01j9abc123",
  "reviewedAt": "2026-04-28T09:14:00.000Z"
}

Both are true. You onboarded them, and you onboarded them despite a failed face match. If your record only stored approved, you could not answer why that was allowed, which is the question your own regulator asks about every exception. reason and reasonCode stay populated for the same purpose: they describe what was overridden.

Branch on status. Store checkStatus alongside it.

Decisions by a person

verification.status_updated fires whenever somebody changes a verification's top-line status from the dashboard.

{
  "verificationId": "ver_01j9xyz456",
  "subjectType": "individual",
  "status": "awaiting_resubmission",
  "checkStatus": "failed",
  "decision": "RESUBMISSION",
  "reviewedById": "usr_01j9abc123",
  "reviewedAt": "2026-04-28T09:14:00.000Z",
  "entityId": "ent_01j9def789",
  "resubmission": {
    "url": "https://trust.myaza.co/verify/hs_live_abc123",
    "steps": ["document-capture"],
    "full": false,
    "expiresAt": "2026-05-05T09:14:00.000Z"
  },
  "environment": "PRODUCTION"
}

decision is APPROVED, DECLINED or RESUBMISSION.

On a resubmission, resubmission.url is the link to send the applicant. They redo only the steps in steps; full: true means the reviewer asked for the whole flow. We hold no contact details for your users, so delivering that link is yours to do.

The reviewer's internal note is deliberately not included. It is free text somebody wrote about your applicant, so it stays in your dashboard audit log. The short message written for the applicant travels on the resubmission link instead.

A reviewer may change their mind, in which case a second verification.status_updated arrives for the same verification. Treat the latest reviewedAt as current.

Captured media

Build withCopy prompt

Verification events carry a media object: a map of the images and videos captured during the flow. Each value is an absolute URL (not the bytes themselves). Fetch each one from your backend with a secret (sk_) key as a Bearer token (media is sensitive, so a publishable key returns 403 secret_key_required):

curl -H "Authorization: Bearer sk_live_..." \
  https://trust.myaza.app/api/kyc/verifications/ver_01j9xyz456/media/selfie \
  --output selfie.jpg

The URLs are scoped to the secret key's organisation and environment (a sandbox key cannot read production media) and do not expire. The object only contains the kinds that were actually captured (a number-only-ID flow has just selfie + livenessVideo), and is null when no media is associated with the event.

Verifying the signature

Build withCopy prompt

Compute HMAC-SHA256(rawBody, endpointSecret) and compare it to the X-Myaza-Signature header using a constant-time comparison. Always use the raw request body, not a re-serialised JSON object, or the signature won't match.

Your endpoint secret is shown when you create the endpoint in the dashboard.

// Node.js / Express
const crypto = require('crypto');

app.post('/webhooks/myaza', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-myaza-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.MYAZA_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

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

  const event = JSON.parse(req.body);
  // process event.event / event.data …
  res.status(200).send('OK');
});

# Python / Flask
import hmac, hashlib
from flask import request, abort

@app.route('/webhooks/myaza', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Myaza-Signature', '')
    expected = 'sha256=' + hmac.new(
        WEBHOOK_SECRET.encode(), request.get_data(), hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)
    event = request.get_json()
    return 'OK', 200

Retries

Build withCopy prompt

A delivery that doesn't receive a 2xx response (or times out) is retried with exponential backoff. After 5 failed attempts the delivery is marked FAILED and can be retried manually from the dashboard.

Best practices

Build withCopy prompt

• Verify the signature before processing the payload.
• Respond 2xx immediately, then do heavy work asynchronously to avoid timeouts and retries.
• Be idempotent. The same delivery may arrive more than once; deduplicate on X-Myaza-Delivery (or verificationId).
• Store the secret in an environment variable, never in source.
• Test on sandbox before enabling production endpoints.