Verify backend events safely.

content-type: application/json
x-hg-event-id: evt_xxx
x-hg-event: verification.completed
x-hg-project-id: project_xxx
x-hg-timestamp: 1780249541000
x-hg-signature: hex_signature

{
  "event_id": "evt_xxx",
  "event": "verification.completed",
  "success": true,
  "verified_human": true,
  "unique_for_action": true,
  "already_verified": false,
  "project_id": "project_xxx",
  "action": "hg_verify_action_key_xxx",
  "created_at": "2026-07-01T00:00:00.000Z"
}

{
  "event_id": "evt_xxx",
  "event": "auth.completed",
  "success": true,
  "verified_human": true,
  "project_id": "project_xxx",
  "partner_id": "partner_xxx",
  "partner_user_id": "puser_xxx",
  "auth_session_id": "authsess_xxx",
  "action": "hg_auth_action_key_xxx",
  "expires_at": "2026-08-01T00:00:00.000Z",
  "created_at": "2026-07-01T00:00:00.000Z"
}

{
  "event_id": "evt_xxx",
  "event": "callback.test",
  "success": true,
  "test": true,
  "project_id": "project_xxx",
  "partner_id": "partner_xxx",
  "message": "Human Gateway callback test delivery.",
  "triggered_by": "partner_user_xxx",
  "triggered_by_role": "admin",
  "created_at": "2026-07-01T00:00:00.000Z"
}

signed_message = "${x-hg-timestamp}.${rawBody}"
x-hg-signature = HMAC_SHA256(callback_secret, signed_message)

// Correct: verify the exact raw request body.
const body = await request.text();

// Incorrect: parsing JSON before verification can break signatures.
const payload = await request.json();

import { NextResponse } from "next/server";
import {
  HumanGatewayCallbackError,
  verifyCallback,
} from "@human-gateway/sdk/server";

export async function POST(request: Request): Promise<Response> {
  const callbackSecret = process.env.HG_CALLBACK_SECRET;
  const expectedProjectId = process.env.HG_PROJECT_ID;

  if (!callbackSecret || !expectedProjectId) {
    return NextResponse.json(
      {
        success: false,
        error: "missing_human_gateway_config",
      },
      { status: 500 }
    );
  }

  const body = await request.text();

  try {
    const callback = verifyCallback({
      body,
      headers: request.headers,
      secret: callbackSecret,
      expectedProjectId,
    });

    // Store callback.event_id and process it idempotently.
    // If this event_id was already processed, return 200
    // without repeating business logic.

    if (callback.event === "verification.completed") {
      const payload = callback.payload;

      // payload is validated and typed as verification.completed.
      // Persist verified state for payload.action.
    }

    if (callback.event === "auth.completed") {
      const payload = callback.payload;

      // payload is validated and typed as auth.completed.
      // Reconcile payload.partner_user_id and payload.auth_session_id.
    }

    if (callback.event === "callback.test") {
      const payload = callback.payload;

      // Operational test event. Do not treat it as a Verify/Auth completion.
      console.log(payload.message);
    }

    return NextResponse.json({
      success: true,
      received: true,
      event_id: callback.event_id,
      event: callback.event,
      project_id: callback.project_id,
    });
  } catch (error) {
    if (error instanceof HumanGatewayCallbackError) {
      return NextResponse.json(
        {
          success: false,
          error: error.code,
        },
        { status: 401 }
      );
    }

    return NextResponse.json(
      {
        success: false,
        error: "callback_error",
      },
      { status: 500 }
    );
  }
}

HG_PROJECT_ID=project_xxx
HG_CALLBACK_SECRET=your_callback_secret

1. Receive callback.
2. Verify signature and timestamp.
3. Check whether event_id already exists.
4. If event_id exists, return 200 without repeating work.
5. If event_id is new, store it.
6. Process the business action.
7. Mark the event as processed.
8. Return 200.

{
  "success": true,
  "received": true
}

Security checklist
- Use HTTPS callback URLs in production
- Keep HG_CALLBACK_SECRET only on the backend
- Never expose callback secrets with NEXT_PUBLIC_
- Read the raw body before parsing JSON
- Verify x-hg-signature
- Validate x-hg-timestamp freshness
- Validate expectedProjectId
- Store event_id for idempotency
- Return 2xx only after accepting the callback
- Rotate the callback secret if it may be exposed