# Faundit Webhooks ## When to Use This Skill * Setting up Faundit webhook handlers * Debugging Faundit signature verification failures * Understanding Faundit event types (`item-status`, `request-status`) and payloads * Handling lost-and-found item and request status changes (delivered, finished, expired, etc.) ## Verification (core) Faundit signs each webhook with HMAC-SHA256 (hex) and delivers two headers you care about: * `X-Faundit-Signature-Next` — current (v1) scheme, signs `v1::` (payload integrity). Prefer this. * `X-Faundit-Timestamp` — the timestamp used in the signed string. * `X-Faundit-Signature` — deprecated (v0) scheme, signs `v0:` only (no body integrity). Avoid. There is no official Faundit SDK — verify manually. Use the raw request body (before `JSON.parse`), and build the signed string as `v1:` + the `X-Faundit-Timestamp` value + `:` + raw body. ```javascript const crypto = require('crypto'); // Verify the current v1 signature (X-Faundit-Signature-Next) function verifyFaunditWebhook(rawBody, timestamp, signatureNext, secret) { if (!signatureNext || !timestamp) return false; const signedContent = `v1:${timestamp}:${rawBody}`; // rawBody = unparsed request body const expected = crypto .createHmac('sha256', secret) .update(signedContent) .digest('hex'); try { return crypto.timingSafeEqual( Buffer.from(signatureNext, 'hex'), Buffer.from(expected, 'hex') ); } catch { return false; // length mismatch = invalid } } ``` > For complete handlers with route wiring, event dispatch, and tests, see: > > * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/faundit-webhooks/examples/express/) > * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/faundit-webhooks/examples/nextjs/) > * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/faundit-webhooks/examples/fastapi/) ## Common Event Types Faundit sends only two event types. The `event-type` field names the event; the granular status is the `data.status` field (not a separate event). | `event-type` | Triggered when | `data.status` values | | --- | --- | --- | | `item-status` | A found/lost item changes status | `contact-missing`, `waiting-response`, `wrong-owner`, `pickup-by-guest`, `left-behind`, `finished`, `shipment-paid`, `pickup-scheduled`, `in-route`, `delivered`, `deleted`, `expired`, `anonymized` | | `request-status` | A lost-item request changes status | `registered`, `not-found`, `resolved`, `deleted`, `expired`, `anonymized` | Payload shape (both events): ```json { "event-type": "item-status", "data": { "id": 12345, "timestamp": "2026-01-15T10:30:00Z", "status": "delivered", "locationID": "loc_abc123" } } ``` > Note (API v2): Members/`faundit_memberID` were renamed to Locations/`locationID`. Legacy IDs are still accepted. > For the full event reference, see [Faundit Webhooks docs](https://faundit.gitbook.io/faundit-api-v2/webhooks). ## Environment Variables ```bash FAUNDIT_WEBHOOK_SECRET=your_signing_secret # request from tech@faundit.com (not self-service) ``` ## Local Development ```bash # Start tunnel (no account needed) npx hookdeck-cli listen 3000 faundit --path /webhooks/faundit ``` ## Reference Materials * [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/faundit-webhooks/references/overview.md) - Faundit webhook concepts, events, payloads * [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/faundit-webhooks/references/setup.md) - Getting the signing secret, registering your endpoint * [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/faundit-webhooks/references/verification.md) - Signature verification details and gotchas