Quickstart

This guide takes you from zero to a verified, fanned-out webhook in about three minutes.

1. Create an API key

Go to /dashboard/api-keys, click New API key, and check Webhooks → webhooks:write in the scope picker (it includes webhooks:read). Save the key — you will only see it once.

2. Create a source

A source represents a single third-party webhook origin. Each source gets its own ingest URL and signing secret.

curl -X POST https://app.krafter.dev/api/v1/webhooks/sources \
  -H "Authorization: Bearer $KRAFTER_KEY" \
  -H "content-type: application/json" \
  -d '{
        "name": "Stripe production",
        "provider": "stripe",
        "signing_secret": "whsec_..."
      }'

The response includes the public ingest URL:

{
  "data": {
    "id": "...",
    "slug": "wh_aB3xY7q1",
    "url": "https://app.krafter.dev/in/wh_aB3xY7q1",
    "destinations_count": 0,
    "provider": "stripe",
    "enabled": true
  }
}

Copy url and paste it into your Stripe Dashboard → Developers → Webhooks → Add endpoint. Stripe will start posting events immediately.

3. Add a destination

A destination is one of your own URLs that should receive forwarded events. You can add many; each can filter by event type.

curl -X POST https://app.krafter.dev/api/v1/webhooks/sources/$SOURCE_ID/destinations \
  -H "Authorization: Bearer $KRAFTER_KEY" \
  -H "content-type: application/json" \
  -d '{
        "url": "https://api.your-app.com/webhooks/stripe",
        "event_filter": ["invoice.paid", "charge.succeeded"]
      }'

The response returns the secret once, on creation. Save it — you will sign-verify forwarded deliveries with it.

{
  "data": {
    "id": "...",
    "url": "https://api.your-app.com/webhooks/stripe",
    "event_filter": ["invoice.paid", "charge.succeeded"],
    "enabled": true,
    "secret": "whsec_..."
  }
}

4. Verify forwarded deliveries

Krafter signs every forwarded delivery using the destination secret. The full signing scheme — headers, HMAC algorithm, retry behaviour — is identical to every other Krafter outgoing webhook and is documented at Outgoing delivery.

5. Replay if needed

Every event is persisted (subject to the source's retention_days). List events for a source, pick any one, and replay it:

curl -X POST \
  "https://app.krafter.dev/api/v1/webhooks/sources/$SOURCE_ID/events/$EVENT_ID/replay" \
  -H "Authorization: Bearer $KRAFTER_KEY"

Returns 202 Accepted with the count and IDs of destinations queued. See the Replay guide for partial-fan-out.

What's next

• Providers — Stripe / GitHub / Shopify / Generic signature formats
• API → Sources — full source CRUD reference
• API → Destinations — destination CRUD, test sends, secret rotation