Skip to content
Akedly
Tutorials

Add the V2 widget

Akedly hosts the whole verification screen. You embed it and read the result.

Build with AI agents

Add the V2 widget

Creating the pipeline, attaching a widget, and embedding it.

Open the video in Google Drive

Note:

Widget or REST — pick one deliberately

The widget means no UI work and no proof-of-work handling, at the cost of Akedly owning the screen your user sees. If you need your own design, use the V1.2 REST API instead.

What you need

  • A pipeline created as V2 — a V1.2 pipeline is rejected when attached to a widget
  • A page you can paste a snippet into

Steps

  1. Create a V2 pipeline.

    Set the API Version to V2 at creation. Widgets accept V1 or V2; V1.2 is the one version they refuse.

  2. Create a widget and attach it.

    The widget carries the branding, the security layers, and the rate limits.

    View in dashboardAuthentication → Setup → Widgets(opens in a new tab)

    Create a widget and attach it to your V2 pipeline.

  3. Brand it.

    Company name, logo and colours come from the Branding Studio and from your company profile, not from code.

  4. Embed it.

    Copy the snippet from the widget page into your own page. The exact attributes are on the V2.0 Widgets page.

  5. Read the result.

    Two ways, and you usually want both — the redirect back to your front end for the user's benefit, and the backend webhook for the truth.

Warning:

If your server misses the widget's backend webhook, Akedly retries it for about 8½ hours (the schedule). Retries can deliver the same result twice, so skip a svix-id you have already processed. If the verification matters, still confirm it from the API rather than treating the webhook as your only record.

When it breaks

  • The widget refuses the pipeline — it is V1.2. Create a V2 pipeline; the version cannot be changed to V1.2 afterwards.
  • Verification succeeds but nothing reaches your server — check the callback URL is set and answers a 2xx within 10 seconds, without redirecting. Failed deliveries are normally retried for about 8½ hours — see Retries.
  • Codes rejected at the last step — a fixed six-digit input. Widgets can issue 4, 5 or 6 digits.
  • The widget says “Turn on cookies to continue” — the browser blocks website storage, which the widget needs. The user follows the on-screen steps; in an iframe, add clipboard-write to allow so Copy link works. See When the browser blocks cookies.

Where to go next