Agent skill
Fingerprint Webhooks Skill
Receive and verify Fingerprint webhooks. Use when configuring Fingerprint webhook endpoints, debugging fpjs-event-signature signatures, or handling identification.
Install this skill
npx skills add hookdeck/webhook-skills --skill fingerprint-webhooks
Receive Fingerprint identification results and Smart Signals.
When to Use This Skill
- Configure a receiver for Fingerprint webhook deliveries.
- Diagnose
fpjs-event-signatureverification failures. - Handle
identification.
Setup
Create a webhook in the Fingerprint dashboard, enable signature protection, and save the symmetric key shown at creation. Send an identification request to produce a delivery.
Set FINGERPRINT_ in the server environment. Read setup before enabling delivery.
Verification (core)
fpjs-event-signature contains v1=<hex> 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
Each delivery is an identification result, with event_id and identification in the current format. There is no event-name discriminator. Older webhook formats differ. Accept any matching v1 digest and ignore other signature versions.
Use event_id to identify a current-format delivery. Verify before using identification data for fraud decisions; signature verification alone does not prevent replay.
Local Development
npx hookdeck-cli listen 3000 fingerprint --path /webhooks/fingerprint
Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.