Przejdź do treści
Biblioteka skilli
DevOps i chmura · Integracja z narzędziem

convox-webhooks

/convox-webhooks

Odbiera i weryfikuje webhooki Convox, czyli PaaS uruchamiający środowiska Rack na własnej chmurze, i obsługuje zdarzenia budżetu oraz wydań.

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
17
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/convox/route.ts, examples/nextjs/test/webhook.test.ts, examples/nextjs/vitest.config.ts

Co robi i kiedy

Odbiera i weryfikuje webhooki Convox, czyli PaaS uruchamiający środowiska Rack na własnej chmurze, i obsługuje zdarzenia budżetu oraz wydań.

Oryginalny opis (EN)

Receive and verify Convox webhooks (the PaaS that runs Racks on your own cloud). Use when setting up Convox webhook handlers, debugging Convox-Signature verification (t=, v1=, webhook_signing_key), or handling events like build:create, release:promote, app:budget:cap and app:budget:auto-shutdown:fired.

Jak działa

  1. When to Use This Skill
  2. Verification (core)
  3. Payload Shape
  4. Common Event Types
  5. Environment Variables
  6. Local Development
  7. Reference Materials
  8. Recommended: webhook-handler-patterns
  9. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 129 linii, 860 słów
Podgląd SKILL.md
---
name: convox-webhooks
description: >
  Receive and verify Convox webhooks (the PaaS that runs Racks on your own
  cloud). Use when setting up Convox webhook handlers, debugging
  Convox-Signature verification (t=, v1=, webhook_signing_key), or handling
  events like build:create, release:promote, app:budget:cap and
  app:budget:auto-shutdown:fired.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# Convox Webhooks

[Convox](https://convox.com) runs Racks on your own cloud account. A Rack POSTs a JSON webhook when an app is created, a build or release changes state, a budget cap is crossed, an auto-shutdown countdown starts or ends, or a scale or trigger override changes.

> Signing is opt-in: set the webhook_signing_key rack parameter (Rack 3.24.6 or later) and paste the same value. Without it, deliveries are unsigned and fail verification.

Delivery is best-effort, fire-and-forget, and **never retried**, not even on a 5xx. Events can arrive out of order or twice. Respond quickly (the default dispatch timeout is 30 seconds) and treat the feed as a notification channel, not a queue.

## When to Use This Skill

- How do I receive Convox webhooks?
- How do I verify the `Convox-Signature` header?
- Why does my Convox webhook signature verification fail?
- How do I turn on webhook signing and rotate the `webhook_signing_key`?
- How do I handle `build:create`, `release:promote` or `app:budget:cap` events?
- Why am I seeing the same Convox event twice, or out of order?

## Verification (core)

| Part | Value |
|------|-------|
| Header | `Convox-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>...]` |
| Signed message | the `t` string exactly as it appears in the header, a literal `.`, then the raw body bytes |
| MAC | HMAC-SHA256, lowercase hex, key = the `webhook_signing_key` value as UTF-8 (**not** hex-decoded) |
| Rotation | one `v1=` per active key (up to 4): accept if **any** matches; ignore other keys such as `v0` |

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

// rawBody: the exact bytes received (express.raw({ type: '*/*' }) / await request.arrayBuffer())
function verifyConvox(rawBody, header, secret) {
  let t = null;
  const sigs = [];
  for (const part of header.split(',')) {
    const i = part.indexOf('=');
    const key = part.slice(0, i).trim(), value = part.slice(i + 1).trim();
    if (i > 0 && key === 't' && t === null) t = value;
    else if (i > 0 && key === 'v1') sigs.push(value);
  }
  if (!t || !/^\d+$/.test(t)) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
  // Validate the format before decoding: Buffer.from(x, 'hex') silently drops bad characters
  return sigs.some((s) => /^[0-9a-fA-F]{64}$/.test(s) && crypto.timingSafeEqual(Buffer.from(s, 'hex'), expected));
}
```

Missing or empty header, malformed value, or no matching `v1`: respond `401`. Verify first, then parse the JSON.

**Timestamp window is opt-in.** Convox's own samples reject deliveries more than 5 minutes old, but Hookdeck retries and replays resend the original `t`, and Hookdeck applies no tolerance itself, so a fixed window rejects legitimate redeliveries. The examples skip the check by default. Set `CONVOX_WEBHOOK_TOLERANCE_SECONDS` to a positive number of seconds (`t` is Unix seconds) to turn it on; unset or `0` means off. The signature has no nonce, so for replay protection dedupe on `data.tick_id` + `action`.

The Python version and more detail are in [references/verification.md](references/verification.md).

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

## Payload Shape

Every payload has `action`, `status`, `timestamp` and a `data` object. Dispatch on `action`:

```json
{
  "action": "app:budget:auto-shutdown:cancelled",
  "status": "success",
  "timestamp": "2026-04-27T10:30:00Z",
  "data": { "app": "myapp", "rack": "rack1", "actor": "alice@example.com",
            "tick_id": "tick-2026-04-27T10:30:00Z-3a7b4c2d8e9f4a6b8c4d3e2f1a0b9c8d",
            "cancel_reason": "reset-during-armed" }
}
```

`status` qualifies some events (`success` or `error` on `build:create`, `start` on `release:promote`, `skipped` on `release:prometheus-skipped`). The docs tell receivers to ignore unknown actions and unknown fields.

## Common Event Types

Convox documents 35 actions; the full list is in [references/overview.md](references/overview.md). The examples handle these and log the rest:

| Action | Fired when | Key fields |
|--------|------------|------------|
| `app:create` | `convox apps create` succeeds | `data.app`, `data.actor` |
| `build:create` | A build starts or fails (`status` is `error` on failure) | `data.app`, `data.message` |
| `release:promote` | A promote starts (`status: "start"`) | `data.app`, `status` |
| `app:budget:cap` | `monthlyCapUsd` is crossed | `data.app` |
| `app:budget:auto-shutdown:fired` | The countdown elapsed and services scaled to zero | `data.app`, `data.tick_id` |
| `app:budget:auto-shutdown:cancelled` | An armed countdown was cancelled | `data.cancel_reason`, `data.tick_id` |

## Environment Variables

```bash
CONVOX_WEBHOOK_SECRET=your_webhook_signing_key   # the webhook_signing_key Rack parameter, used as-is
CONVOX_WEBHOOK_TOLERANCE_SECONDS=0               # Optional replay window; a positive value opts in
```

## Local Development

```bash
npx hookdeck-cli listen 3000 convox --path /webhooks/convox
```

No account required. The CLI creates a guest account on first run and gives you a tunnel and a web UI for inspecting requests. Use port `8000` for the FastAPI example.

## Reference Materials

- [references/overview.md](references/overview.md) - What Convox webhooks are, all 35 actions, delivery semantics
- [references/setup.md](references/setup.md) - Set `webhook_signing_key`, add the receiver URL, rotate keys
- [references/verification.md](references/verification.md) - Signature details, Python version, gotchas

## Recommended: webhook-handler-patterns

Install the patterns skill alongside this one for production-ready handlers:

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md)
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)

## Related Skills

- [duffel-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/duffel-webhooks) - Same `t=`/`v1=` hex HMAC-SHA256 shape over `{t}.{body}`
- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - `t=`/`v1=` signature header with a timestamp
- [render-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/render-webhooks) - Render deploy and service events
- [heroku-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/heroku-webhooks) - Heroku app, build and release events
- [railway-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/railway-webhooks) - Railway deployment events
- [northflank-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/northflank-webhooks) - Northflank platform events
- [vercel-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/vercel-webhooks) - Vercel deployment events
- [argo-cd-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/argo-cd-webhooks) - Kubernetes deployment notifications
- [circleci-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/circleci-webhooks) - CI/CD pipeline events
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure
Pliki w paczce (20)
  • SKILL.md 8 KB
  • examples/express/.env.example 1 KB
  • examples/express/README.md 1 KB
  • examples/express/package.json 1 KB
  • examples/express/src/index.js 5 KB
  • examples/express/test/webhook.test.js 7 KB
  • examples/fastapi/.env.example 1 KB
  • examples/fastapi/README.md 1 KB
  • examples/fastapi/main.py 6 KB
  • examples/fastapi/requirements.txt 1 KB
  • examples/fastapi/test_webhook.py 7 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/convox/route.ts 5 KB
  • examples/nextjs/test/webhook.test.ts 8 KB
  • references/overview.md 6 KB
  • references/setup.md 3 KB
  • references/verification.md 5 KB

Wersje

W bazie nie ma innych skilli o nazwie convox-webhooks.

Migawka bazy z 13.11.2026 · wersja paczki 852c1b2d2897 (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

  • 100mautic-webhooks
    Odbiera i weryfikuje webhooki Mautic, w tym podpis Webhook-Signature, oraz obsługuje zdarzenia takie jak mautic.lead_post_save_new, mautic.form_on_submit i mautic.email_on_open.
  • 100xtremepush-webhooks
    Odbiera i weryfikuje webhooki Xtremepush, sprawdza podpis X-Xtremepush-Signature i obsługuje zdarzenia kampanii.

Uwagi i zgłoszenia

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