Ingest

The ingest endpoint is the public URL where external services send webhook events. Each source gets a unique ingestion URL at /v1/ingest/<source_id>.

The endpoint accepts any HTTP method (GET, POST, PUT, PATCH, DELETE) and stores the request method, headers, and body as an event. No authentication is required — security is handled through optional signature verification, deduplication, and IP filtering configured on the source.

Ingest Event

ANY /v1/ingest/:source_id

Receive a webhook event at the source's ingestion URL. Accepts any HTTP method.

Authentication: None (verification configured per source).

bash
curl -X POST https://hookstream.io/v1/ingest/src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1709,v1=abc..." \
  -d '{
    "type": "payment.completed",
    "data": {
      "id": "pay_xyz789",
      "amount": 2999,
      "currency": "usd"
    }
  }'

json
{
  "event_id": "evt_d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
  "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

Signature verification

If the source has a verification_type configured, hookstream validates the request signature before accepting the event. Supported methods:

Failed verification returns 401 Unauthorized. Configure the secret on the source via verification_secret.

Deduplication

hookstream supports three dedup strategies to avoid processing the same event twice:

Duplicate events return 200 OK so senders don't retry. hookstream still records the duplicate for audit visibility but does not route it to destinations.

IP filtering

Sources can define IP allow/deny lists using individual addresses or CIDR ranges. Requests from blocked IPs receive 403 Forbidden.

Response codes

Related