Skip to content
Akedly
Gateway

Results and callbacks

Read the webhook payload your server receives after a verification, and where to verify its signature.

Step 4: Handle Callbacks

Backend Webhook Payload

If you configure a backendCallbackURL in your integration settings, Akedly sends a POST request to your server with complete verification details.

Webhook Timing:

The webhook is sent:

  • Immediately after successful verification (OTP verified)
  • Immediately after failed verification (invalid OTP, expired, etc.)

Gateway callbacks are signed

The Gateway callback is an envelope with top-level status and timestamp, plus attempt, transaction, metadata, and optional error data. This contract covers the verification-result callback; selected signed otp.channels.resolved, otp.channels.updated and otp.message.status events use the separate signed OTP event contract.

  • Name
    Payload
    Type
    object
    Description
    The envelope contains status, timestamp, widgetAttempt, transaction, transactionReq, publicMetadata, and privateMetadata; failed callbacks may also include error.
  • Name
    Dev-mode marker
    Type
    widgetAttempt.isTest
    Description
    A test-pair attempt is marked by widgetAttempt.isTest. It is not a top-level webhook field.
  • Name
    Signature
    Type
    svix headers
    Description
    The gateway screen success path supplies the integration signing secret to the common dispatcher, which generates svix-id, svix-timestamp, and svix-signature.
  • Name
    OTP events
    Type
    excluded for test attempts
    Description
    An attempt marked widgetAttempt.isTest still receives this verification-result callback, but it does not emit signed otp.channels.resolved, otp.channels.updated or otp.message.status events.

Webhook Payloads

{
  "status": "success",
  "timestamp": "2026-10-01T12:00:42.150Z",
  "widgetAttempt": {
    "attemptId": "attempt_a1b2c3d4e5f67890",
    "widgetId": "widget_x1y2z3",
    "userId": "6821bb199f9cfd6b2754e6ef",
    "status": "verified",
    "isTest": false,
    "verificationAddress": {
      "phoneNumber": "+201****7890",
      "email": null
    },
    "otpConfig": {
      "digits": 6,
      "resendCount": 0
    },
    "publicMetadata": {
      "orderId": "order_abc789"
    },
    "createdAt": "2026-10-01T11:59:40.000Z",
    "expiresAt": "2026-10-01T12:04:40.000Z",
    "captchaVerifiedAt": "2026-10-01T11:59:52.500Z",
    "otpRequestedAt": "2026-10-01T11:59:59.800Z",
    "completedAt": "2026-10-01T12:00:42.120Z"
  },
  "transaction": {
    "transactionID": "ae2eacaebe3ed78b105498d5d0cfe54f11b4130a0847d67b36927752148679e5",
    "status": "Successful",
    "verificationAddress": {
      "phoneNumber": "+201234567890"
    },
    "OTP": "123456",
    "resolvedChannel": "whatsapp",
    "channels": [
      "whatsapp"
    ],
    "isTest": false,
    "userID": "6821bb199f9cfd6b2754e6ef",
    "pipelineID": "6821bba09f9cfd6b2754e752",
    "creationDate": "2026-10-01T12:00:00.000Z",
    "expirationDate": "2026-10-01T12:03:00.000Z",
    "updateDate": "2026-10-01T12:00:42.120Z"
  },
  "transactionReq": {
    "_id": "6a1f0c2f9d1b4a0012345679",
    "mainTransactionID": "ae2eacaebe3ed78b105498d5d0cfe54f11b4130a0847d67b36927752148679e5",
    "status": "Successful",
    "isTest": false,
    "channels": [
      "whatsapp"
    ],
    "sentVerificationDate": "2026-10-01T12:00:01.200Z",
    "inputOTP": "123456",
    "verificationDate": "2026-10-01T12:00:42.120Z",
    "creationDate": "2026-10-01T12:00:00.300Z",
    "expirationDate": "2026-10-01T12:03:00.300Z"
  },
  "publicMetadata": {
    "orderId": "order_abc789"
  },
  "privateMetadata": {
    "internalUserId": "internal_xyz"
  }
}

Verifying Webhook Signatures

When signature headers are present, the JSON payload above is what gets signed — verify the signature on the raw request bytes before acting on the body. The examples parse the body first only to route on eventType, and keep the raw bytes for the check; nothing in a signed request is acted on until it verifies. A verification result with no svix-signature header is neither trusted nor rejected: the examples above answer 200 and confirm the attempt with a status lookup before marking anything verified. OTP event envelopes require a valid signature and are rejected when unsigned.