Agent skill

Authgear Webhooks Skill

Receive and verify Authgear webhooks. Use when configuring Authgear webhook endpoints, debugging x-authgear-body-signature signatures, or handling user.created, user.authenticated, user.deleted.

Install this skill

npx skills add hookdeck/webhook-skills --skill authgear-webhooks

Receive Authgear non-blocking user and identity events.

When to Use This Skill

Configure a receiver for Authgear webhook deliveries.
Diagnose x-authgear-body-signature verification failures.
Handle user.created, user.authenticated, user.deleted.

Setup

In the Authgear portal, configure a non-blocking webhook under Advanced > Hooks. Reveal the project secret under Webhook Signature; reauthentication may be required. Register an HTTPS endpoint.

Only non-blocking events are supported. Blocking events expect a synchronous response from the receiver.

Set AUTHGEAR_WEBHOOK_SECRET in the server environment. Read setup before enabling delivery.

Verification (core)

x-authgear-body-signature contains a bare hex digest over the raw body. Use HMAC-SHA256 with the secret's UTF-8 bytes. Verify the original bytes before parsing JSON. Validate the digest format, then compare equal-length buffers in constant time.

After extracting the documented digest and constructing message as described in verification, the comparison is:

const expected = crypto.createHmac('sha256', secret).update(message).digest();
if (digest.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(digest)) return false;
const received = Buffer.from(digest, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);

No timestamp is included in the signed message. These examples do not invent an age check from unsigned fields.

Complete handlers and tests: Express, Next.js, FastAPI.

Event Handling

Read the top-level type. An identity object's type describes the identity, not the event. Blocking hooks require a synchronous decision response and are outside this receiver's scope.

Return 2xx for accepted non-blocking events. Keep business processing idempotent and acknowledge events you intentionally ignore.

Local Development

npx hookdeck-cli listen 3000 authgear --path /webhooks/authgear

Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.