Authiflow

Developer integration

Order in, verdict back.

Authiflow is a pair of JSON webhooks secured with a per-shop key pair. You submit orders that need verification and react to the verdict we post back. No SDK, any language that speaks HTTPS. Here is the whole flow and every call.

AuthAuthorization: Basic base64("<publicKey>:<secretKey>")

The flow

Every webhook, in the order it happens. Green steps are ours, the rest are yours.

  1. 1
    You

    Submit the order

    Send an order that needs checking. Only verification_required: true is ingested. Idempotent on order_number. The response returns the center address as ship_to.

    POST/api/webhooks/orders
  2. 2
    You

    Ship to the center

    Send the item to the ship_to address, not to the customer. Push the inbound label (shop to center) so the order is trackable in Authiflow, with live status on the board.

    POST/api/webhooks/status·{ status: "shipped" }
  3. 3
    You / carrier

    Arrival at the center

    When it is delivered, mark it received. This starts the two working-day verification window (in_verification).

    POST/api/webhooks/status·{ status: "received" }
  4. AF
    Authiflow

    We verify

    Our specialists inspect the item at the center. The verdict is passed, failed or needs_review.

  5. AF
    Authiflow

    We post the verdict

    On every status change we POST to the feedback URL you configured, signed with your feedbackSecret. Match on status. A pass includes a certificate_url.

    ← CALLBACKyour feedbackUrl
  6. 6
    You

    Release the item

    On a pass, ship onward to the customer; on a fail it returns to you. Push the outbound leg so it reaches shipped_to_customer / returned_to_seller and stays tracked. Upload the label as a PDF if the center should print it.

    POST/api/webhooks/status·{ status: "shipped" }POST/api/webhooks/label
×
You · anytime before the center

Cancel or refund

If the order is refunded before it reaches the center, cancel it and it is removed from Authiflow (only while incoming or shipped).

POST/api/webhooks/status·{ status: "cancelled" }

Keep every order trackable

Tracking runs through /api/webhooks/status, and your shop is the only party that holds the shop-to-center and outbound labels. Pushing each milestone is what puts live tracking on every order and starts an accurate two working-day SLA, from checkout through to delivery. Treat it as part of the flow, not an extra: without it an order carries no tracking until it is physically checked in at the center.

Every endpoint

Inbound calls use HTTP Basic with your key pair. The feedback callback is the one you build.

POST
/api/webhooks/orders
Submit a verification order. Returns ship_to (the center address).
POST
/api/webhooks/status
How orders stay tracked: milestones (shipped, received), the outbound leg, and cancellations.
POST
/api/webhooks/label· multipart/form-data
Upload the customer or return label as a PDF (label_type=customer|return).
POST
/api/webhooks/shopify· X-Api-Key or ?token
Native Shopify order payload. Only orders tagged authiflow are ingested.
GET
/api/center· public
The authentication center address as JSON. No auth needed.
← CALLBACK
your feedbackUrl· Bearer feedbackSecret
We POST every verdict here. This is the callback you implement.

The two payloads that matter

Submit an order, and the verdict you get back. The rest is in the full docs.

Submit → response

POST /api/webhooks/orders
Authorization: Basic base64("pk:sk")

{
  "order_number": "10234",
  "verification_required": true,
  "customer_name": "Jane Doe",
  "customer_email": "jane@example.com",
  "address_line1": "Keizersgracht 1",
  "postal_code": "1015 CJ",
  "city": "Amsterdam",
  "country": "Netherlands",
  "product_name": "Air Jordan 1 Chicago",
  "sku": "555088-134",
  "size": "43"
}

// 201 Created
{
  "ok": true,
  "id": "clx8f...",
  "created": true,
  "ship_to": {
    "name": "Authiflow Authentication Center",
    "address_line1": "Voltastraat 51",
    "postal_code": "3335 KK",
    "city": "Zwijndrecht",
    "country_code": "NL"
  }
}

Verdict → your webhook

POST <your feedbackUrl>
Authorization: Bearer <feedbackSecret>

{
  "order_number": "10234",
  "status": "passed",
  // match on status ^
  "verification_status": "passed",
  "status_label": "Passed",
  "tracking_number": "3SABCD1234567",
  "carrier_status": "Delivered at center",
  "fail_reason": null,
  // set when status = failed ^
  "certificate_url": "https://authiflow.com/api/certificate/clx..?t=..",
  // present on a pass ^
  "source": "authiflow"
}

// respond 2xx to acknowledge

Status reference

The value of status in every verdict. React to the middle three.

incomingReceived. Waiting for you to ship it to the center.
shippedInbound label scanned, on its way to the center.
in_verificationDelivered. The two working-day check is running.
passedAuthentic. A certificate is available.
failedfail_reason is set; the item returns to you.
needs_reviewAn extra check is needed before a final verdict.
shipped_to_customerAfter a pass, dispatched to the customer.
returned_to_sellerAfter a fail, sent back to you.

No Pass, No Shipment.

The full reference, error codes and platform guides live in the developer docs.

Read the docssupport@authiflow.com