Przejdź do treści
Biblioteka skilli
Programowanie · Integracja z narzędziem

spike-api-webhooks

/spike-api-webhooks

Odbiera i weryfikuje webhooki Spike API z danymi zdrowotnymi i z urządzeń, sprawdzając podpis X-Body-Signature.

Repozytorium
webhook-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
20
Skrypty
7
Komentarze HTML
0
Adresy URL w SKILL.md
13
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 7 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: examples/express/src/index.js, examples/express/test/webhook.test.js, examples/fastapi/main.py, examples/fastapi/test_webhook.py, examples/nextjs/app/webhooks/spike-api/route.ts, examples/nextjs/test/webhook.test.ts, examples/nextjs/vitest.config.ts

Co robi i kiedy

Odbiera i weryfikuje webhooki Spike API z danymi zdrowotnymi i z urządzeń, sprawdzając podpis X-Body-Signature.

Oryginalny opis (EN)

Receive and verify Spike API webhooks. Use when setting up Spike API (unified health and wearables data API) webhook handlers, debugging X-Body-Signature verification, or handling record_change, provider_integration_created and provider_integration_deleted events.

Jak działa

  1. When to Use This Skill
  2. Verification (core)
  3. Common Event Types
  4. Delivery Rules
  5. Environment Variables
  6. Local Development
  7. Resources
  8. Recommended: webhook-handler-patterns
  9. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 117 linii, 681 słów
Podgląd SKILL.md
---
name: spike-api-webhooks
description: >
  Receive and verify Spike API webhooks. Use when setting up Spike API (unified
  health and wearables data API) webhook handlers, debugging X-Body-Signature
  verification, or handling record_change, provider_integration_created and
  provider_integration_deleted events.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# Spike API Webhooks

## When to Use This Skill

- How do I receive Spike API webhooks?
- How do I verify Spike API webhook signatures (`X-Body-Signature`)?
- How do I handle `record_change`, `provider_integration_created` or `provider_integration_deleted` events?
- Why is my Spike API webhook signature verification failing?
- Why does Spike API keep retrying my webhook?

## Verification (core)

Spike API signs the **raw request body** with **HMAC-SHA256**, keyed with the
shared secret from the admin console (used as-is, as UTF-8 bytes), and sends the
**bare lowercase hex digest** (no prefix, no timestamp) as the whole
`X-Body-Signature` header value. Always verify against the **raw body**, never
re-serialized JSON. There is no Spike API webhook SDK, so verify manually:

```javascript
const crypto = require('crypto');

function verifySpikeSignature(rawBody, signature, secret) {
  // Check shape first: Buffer.from(x, 'hex') silently drops invalid characters
  if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/i.test(signature)) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature.toLowerCase(), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(expected, received);
}
```

```python
import hashlib, hmac, re

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    if not re.fullmatch(r"[0-9a-fA-F]{64}", signature):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    # Compare bytes, never str
    return hmac.compare_digest(expected.encode(), signature.lower().encode())
```

A missing, empty or malformed header, or a mismatch, is a `401`. Read the body
with `express.raw({ type: '*/*' })` (Express), `await request.arrayBuffer()`
(Next.js) or `await request.body()` (FastAPI), and parse JSON only after the check.

> **For complete handlers with tests**, see [examples/express/](examples/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/).

## Common Event Types

The body is a **JSON array**; one delivery can batch several events, so loop over
every element. Each element carries its own `event_type`.

| Event | Triggered When | Common Use Cases |
|-------|----------------|------------------|
| `record_change` | New or updated data arrives from a provider | Fetch the changed records (`metrics`, `activity_types`, `earliest_record_start_at`..`latest_record_end_at`) |
| `provider_integration_created` | A user connects a provider | Mark the integration active |
| `provider_integration_deleted` | A user's integration is deleted | Stop syncing, clean up |

Treat every parsed field as untrusted: check that the body is an array and that
each element and nested field has the expected type before reading it. See
[references/overview.md](references/overview.md).

## Delivery Rules

Respond with exactly HTTP `200` within 30 seconds. Any other status, a network
error or a timeout is retried up to 10 times (5 s, 2 min, 30 min, 2 h, then every
12 h); after that the event is discarded. Return `200` quickly and process
asynchronously, and make handling idempotent.

## Environment Variables

```bash
# Shared HMAC key from the Spike API admin console
SPIKE_API_WEBHOOK_SECRET=your_spike_api_webhook_secret
```

## Local Development

For local webhook testing, run the Hookdeck CLI via `npx` — no install required:

```bash
npx hookdeck-cli listen 3000 spike-api --path /webhooks/spike-api
```

No account required — the CLI creates a guest account on first run and provides a
local tunnel + web UI for inspecting requests. Express and Next.js examples use
port 3000; the FastAPI example uses `8000`.

## Resources

- [Overview](references/overview.md) - What Spike API webhooks are, event types and payloads
- [Setup](references/setup.md) - Configure the endpoint and get the shared key
- [Verification](references/verification.md) - Signature details and gotchas
- [Express Example](examples/express/) - Express.js implementation
- [Next.js Example](examples/nextjs/) - Next.js App Router implementation
- [FastAPI Example](examples/fastapi/) - Python FastAPI implementation

## Recommended: webhook-handler-patterns

We recommend installing the [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md) — Verify first, parse second, handle idempotently third
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md) — Dedupe deliveries
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md) — Return codes, logging, dead letter queues
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md) — Provider retry schedules, backoff patterns

## Related Skills

- [oura-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/oura-webhooks) - Oura ring health data webhooks
- [polar-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/polar-webhooks) - Polar webhooks
- [strava-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/strava-webhooks) - Strava activity webhooks
- [agentline-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/agentline-webhooks) - Another bare hex HMAC-SHA256 of the raw body
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub webhooks (simple HMAC-SHA256 hex)
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Handler sequence, idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
Pliki w paczce (20)
  • SKILL.md 7 KB
  • examples/express/.env.example 1 KB
  • examples/express/README.md 1 KB
  • examples/express/package.json 1 KB
  • examples/express/src/index.js 3 KB
  • examples/express/test/webhook.test.js 5 KB
  • examples/fastapi/.env.example 1 KB
  • examples/fastapi/README.md 1 KB
  • examples/fastapi/main.py 3 KB
  • examples/fastapi/requirements.txt 1 KB
  • examples/fastapi/test_webhook.py 4 KB
  • examples/nextjs/.env.example 1 KB
  • examples/nextjs/README.md 1 KB
  • examples/nextjs/package.json 1 KB
  • examples/nextjs/vitest.config.ts 1 KB
  • examples/nextjs/app/webhooks/spike-api/route.ts 3 KB
  • examples/nextjs/test/webhook.test.ts 5 KB
  • references/overview.md 2 KB
  • references/setup.md 1 KB
  • references/verification.md 2 KB

Wersje

W bazie nie ma innych skilli o nazwie spike-api-webhooks.

Migawka bazy z 13.11.2026 · wersja paczki 0030436c37d9 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100seatable-webhooks
    Odbiera i weryfikuje webhooki SeaTable, w tym podpis X-Seatable-Signature i zdarzenia zmian bazy (insert_row, modify_row, delete_row).
  • 100paysafe-webhooks
    Odbiera i weryfikuje webhooki Paysafe Payments API, w tym nagłówek Signature oraz zdarzenia PAYMENT_HANDLE_COMPLETED, PAYMENT_COMPLETED i SETTLEMENT_COMPLETED.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.