Results and callbacks
Read the webhook payload your server receives after a verification, and where to verify its signature.
Formerly V2.0 Widgets
Gateway was called V2.0 Widgets, and gateway screens were called widgets. This page was at /authentication/v2/results; old links still work. The API and its field names are unchanged.
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.
Gateway screen webhooks are retried for about 8½ hours
If your server is down, times out, or replies with anything other than 2xx, Akedly sends the same result again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. That is six attempts in total. Each retry can start up to a minute after it is due. Every attempt carries the same body and the same svix-id, so use svix-id to skip repeated deliveries of the same message. It is not a business key: key your records on widgetAttempt.attemptId.
Two things to design around:
- The result has no event envelope. It stays the flat object below, with the same body and signing behavior. The same URL also receives signed
otp.channels.resolved,otp.channels.updatedandotp.message.statusenvelopes when selected on the integration's Webhooks tab. CheckeventTypebefore reading a result'sstatus; these events carrydata.attemptIdfor correlation. See OTP delivery receipts and selection defaults. - Signing does not fail closed. The request is normally signed with the integration's
whsec_secret, but unlike one-way webhooks the gateway screen still sends if signing fails. Treat a missing signature as "unverifiable", not as proof of forgery.
Retries make delivery much more likely but do not guarantee it, so do not make this your only record of a verification. See Webhooks → Retries for the full rules. If a result never arrives, look the attempt up by the attemptId you saved with a transaction status lookup.
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, andprivateMetadata; failed callbacks may also includeerror.
- 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, andsvix-signature.
- Name
- OTP events
- Type
- excluded for test attempts
- Description
- An attempt marked
widgetAttempt.isTeststill receives this verification-result callback, but it does not emit signedotp.channels.resolved,otp.channels.updatedorotp.message.statusevents.
Which channel did the code go out on?
transaction.resolvedChannel is the channel the code ended up on (whatsapp, sms, telegram or
email), and transaction.channels lists every channel it was sent on. Passkey verifications have
neither. See Where is the delivery channel? and the full
field reference.
The top-level failure status and attempt status differ
A failed OTP verification is sent with top-level status: "failed", but the
widgetAttempt.status can still be "otp_requested" because an invalid OTP does not
terminalize the attempt. Branch on the top-level status and inspect error; do not assume the
nested attempt status is always "failed".
Make the handler safe to run twice
These examples find your user by the attemptId you saved on the user record when you created the attempt, stored as akedlyAttemptId. Save it at creation, and look the attempt up with that same id.
The guard is the conditional update on your stored record (verified is not already true), not a flag in memory. Send the welcome email only when that update changed the record.
If you call these steps from a reconciler that uses a status lookup, apply only a success. A lookup's pending or failed is not a new failed attempt and has no error object, so do not log it as one.
A crash between the update and the email can lose the email, and sending the email first can repeat it. If the email must survive a crash, write the email request in the same database transaction as the update (an outbox) and send from that. In SQL, use an update limited to rows not yet verified and check the changed-row count.
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.
