API Overview

HookVault is universal webhook middleware that sits between your event sources and your endpoints. It guarantees delivery with automatic retries, exponential backoff, HMAC-SHA256 payload signing, a Dead Letter Queue for failed events, and one-click replay — so you never lose a webhook again.

HookVault supports two integration modes:

Push Mode — Your backend sends events to POST /v1/events and HookVault delivers them to configured destinations with retries and signatures.
Inbox Mode — Give third-party providers (Stripe, GitHub, Shopify, etc.) your unique inbox URL. HookVault captures, stores, and forwards the payload to your destination.

Pricing

Feature	Free	Pro ($29/mo)	Ultra ($99/mo)	Mega ($299/mo)
Destinations	3	25	100	500
Events / month	1,000	50,000	500,000	5,000,000
Max payload size	64 KB	256 KB	512 KB	1 MB
Retention	3 days	14 days	30 days	90 days
Retry attempts	3	5	8	12
Priority delivery	—	—	—	✓

Rate Limiting

All authenticated endpoints return rate-limit headers so you always know your usage:

Header	Description
`X-RateLimit-Limit`	Maximum events allowed in the current billing window
`X-RateLimit-Remaining`	Events remaining before you hit the cap
`X-RateLimit-Reset`	ISO 8601 timestamp when the window resets (1st of next month)
`X-Request-Id`	Unique request identifier — include this in support requests

Authentication

Authentication is handled automatically by RapidAPI. When you subscribe, the x-rapidapi-key and x-rapidapi-host headers are auto-populated on every request — no manual configuration needed.

The Inbox endpoint (POST /inbox/{tenant_id}/{inbox_token}) is public by design and requires no API key. This allows third-party providers to POST webhooks directly to your capture URL.

Signature Verification

When a signing_secret is configured on a destination, every outbound delivery includes these headers for verification:

X-HookVault-Timestamp — Unix millisecond timestamp of the delivery
X-HookVault-Signature — HMAC-SHA256(secret, timestamp + "." + raw_body)

Verify signatures in your endpoint by computing the same HMAC and comparing. This protects against spoofed deliveries.

Endpoints

System

`GET /health` — Health Check

Returns the current service status, API version, and server timestamp. Use this to verify connectivity before making other calls. No authentication required on RapidAPI.

Example response (200):

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-02-21T12:00:00Z"
}

Inbox (Public)

`POST /inbox/{tenant_id}/{inbox_token}` — Capture Inbound Webhook

This is the public capture URL you give to third-party providers like Stripe, GitHub, or Shopify. When they send a webhook, HookVault stores the payload, then immediately attempts delivery to the linked destination with retries and optional HMAC signing.

Path parameters:

tenant_id — Your tenant identifier (provided when you create a destination)
inbox_token — The unique inbox token for the destination

Example request body:

{
  "event": "payment_intent.succeeded",
  "data": {
    "id": "pi_abc123",
    "amount": 2000
  }
}

Example response (202):

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "created_at": "2026-02-21T12:00:00Z"
}

The status field may return "delivered" immediately if the inline delivery attempt succeeded, or "queued"/"delivering" if retries are in progress.

Destinations

`POST /v1/destinations` — Create Destination

Creates a new delivery destination. A destination defines where webhooks are forwarded to, including the target URL, optional HMAC signing secret, custom headers, timeout, retry count, and backoff configuration.

Each destination automatically generates a unique inbox URL for receiving inbound webhooks from third parties.

Example request body:

{
  "name": "Stripe Webhooks",
  "delivery_url": "https://api.example.com/webhooks/stripe",
  "signing_secret": "whsec_test_secret_123",
  "headers": {
    "Authorization": "Bearer your-token"
  },
  "timeout_ms": 30000,
  "max_attempts": 5
}

Parameters explained:

name (required) — Human-readable label, max 255 characters
delivery_url (required) — The HTTPS endpoint where events are POSTed
signing_secret (optional) — Enables HMAC-SHA256 signatures on outbound deliveries
headers (optional) — Custom headers included in every delivery (e.g., auth tokens)
timeout_ms (optional, default 30000) — Delivery timeout in milliseconds (1000–60000)
max_attempts (optional, default 5) — Maximum delivery attempts before dead-lettering (1–30)

Example response (201):

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Stripe Webhooks",
  "delivery_url": "https://api.example.com/webhooks/stripe",
  "inbox_url": "https://hookvault.p.rapidapi.com/inbox/my-tenant/tk_live_abc123",
  "created_at": "2026-02-21T12:00:00Z"
}

The inbox_url is what you give to Stripe (or any provider) as your webhook endpoint URL.

`GET /v1/destinations` — List Destinations

Returns all destinations configured for your account. Use this to discover destination IDs and inbox URLs.

Example response (200):

[
  {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Stripe Webhooks",
    "delivery_url": "https://api.example.com/webhooks/stripe",
    "inbox_url": "https://hookvault.p.rapidapi.com/inbox/my-tenant/tk_live_abc123",
    "created_at": "2026-02-21T12:00:00Z"
  },
  {
    "id": "e391f2ff-7d65-5c12-a1f7-e812859g1962",
    "name": "GitHub Events",
    "delivery_url": "https://api.example.com/webhooks/github",
    "inbox_url": "https://hookvault.p.rapidapi.com/inbox/my-tenant/tk_live_def456",
    "created_at": "2026-02-20T10:30:00Z"
  }
]

`GET /v1/destinations/{id}` — Get Destination by ID

Returns full details of a single destination, including its timeout, retry count, and timestamps.

Example response (200):

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Stripe Webhooks",
  "delivery_url": "https://api.example.com/webhooks/stripe",
  "inbox_url": "https://hookvault.p.rapidapi.com/inbox/my-tenant/tk_live_abc123",
  "timeout_ms": 30000,
  "max_attempts": 5,
  "created_at": "2026-02-21T12:00:00Z",
  "updated_at": "2026-02-21T12:00:00Z"
}

`PATCH /v1/destinations/{id}` — Update Destination

Partially updates a destination. Only include the fields you want to change. You can update the name, delivery URL, signing secret, headers, timeout, retry count, and backoff settings.

Example request body:

{
  "name": "Updated Webhook Name",
  "delivery_url": "https://api.example.com/webhooks/updated",
  "timeout_ms": 15000
}

Example response (200):

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Updated Webhook Name",
  "delivery_url": "https://api.example.com/webhooks/updated",
  "updated_at": "2026-02-21T13:00:00Z"
}

`DELETE /v1/destinations/{id}` — Delete Destination

Permanently removes a destination and its associated inbox URL. Any queued events for this destination will not be delivered.

Example response (200):

{
  "deleted": true,
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

`POST /v1/destinations/{id}/test` — Send Test Payload

Sends a test webhook to the destination's delivery URL and returns the result. Use this to verify connectivity and response time before routing production traffic.

Example response (200):

{
  "success": true,
  "http_status": 200,
  "latency_ms": 145
}

Events

`POST /v1/events` — Send Event (Push Mode)

Creates a new event and immediately attempts delivery to the specified destination. This is "push mode" — your backend pushes events into HookVault, which handles delivery, retries, and dead-lettering.

Supports idempotency keys to prevent duplicate deliveries. If you send the same idempotency_key + destination_id combination, HookVault returns the existing event instead of creating a duplicate.

Supports scheduled delivery via the optional deliver_at field (ISO 8601 datetime). Events with deliver_at in the future are queued and delivered at the specified time.

Example request body:

{
  "destination_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "event_type": "invoice.paid",
  "idempotency_key": "idem_abc123",
  "payload": {
    "invoice_id": "inv_12345",
    "amount": 9900,
    "currency": "usd"
  },
  "metadata": {
    "source": "billing-service"
  }
}

Parameters explained:

destination_id (required) — UUID of the target destination
event_type (optional) — A label like "invoice.paid" or "user.created" for filtering
idempotency_key (optional) — Prevents duplicate events when retrying from your side
payload (optional) — The JSON body delivered to the destination
metadata (optional) — Extra context stored with the event (not delivered)
deliver_at (optional) — ISO 8601 datetime for scheduled delivery

Example response (202):

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "created_at": "2026-02-21T12:00:00Z"
}

`GET /v1/events` — List Events

Returns a paginated list of events for your account. Filter by status or destination to narrow results.

Query parameters:

status — Filter by: queued, delivering, delivered, failed, dead_letter
destination_id — Filter to a specific destination
limit — Results per page (default 20)
offset — Pagination offset (default 0)

Example response (200):

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "destination_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "event_type": "invoice.paid",
      "status": "delivered",
      "created_at": "2026-02-21T12:00:00Z"
    }
  ],
  "total": 1
}

`GET /v1/events/{event_id}` — Get Event by ID

Returns full details of a single event including payload, metadata, and current delivery status.

Example response (200):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "destination_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "event_type": "invoice.paid",
  "status": "delivered",
  "payload": {
    "invoice_id": "inv_12345",
    "amount": 9900,
    "currency": "usd"
  },
  "metadata": {
    "source": "billing-service"
  },
  "created_at": "2026-02-21T12:00:00Z"
}

`GET /v1/events/{event_id}/attempts` — Get Delivery Attempts

Returns a chronological list of every delivery attempt for an event. Each attempt includes the HTTP status code, latency, and any error text — invaluable for debugging failed deliveries.

Example response (200):

[
  {
    "attempt_no": 1,
    "status": "success",
    "http_status": 200,
    "latency_ms": 145,
    "created_at": "2026-02-21T12:00:01Z"
  }
]

`POST /v1/events/{event_id}/cancel` — Cancel Pending Event

Cancels a pending or queued event before it is delivered. Events that have already been delivered cannot be canceled.

Example response (200):

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "canceled"
}

Replay

`POST /v1/events/{event_id}/replay` — Replay Event

Re-queues a previously delivered or failed event for another delivery attempt. The original payload is re-sent to the destination. Useful when your endpoint was down or returned an error that has since been fixed.

Example response (200):

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued"
}

Dead Letter Queue (DLQ)

`GET /v1/dlq` — List Dead-Lettered Events

Returns events that exhausted all retry attempts or encountered non-retryable errors (e.g., 4xx responses, SSRF-blocked URLs). These events are preserved for inspection and can be replayed after you fix the underlying issue.

Query parameters:

limit — Results per page (default 20)
offset — Pagination offset (default 0)

Example response (200):

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "destination_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "event_type": "invoice.paid",
      "status": "dead_letter",
      "created_at": "2026-02-21T12:00:00Z"
    }
  ],
  "total": 1
}

`POST /v1/dlq/{event_id}/replay` — Replay from DLQ

Moves a dead-lettered event back to the queue for another delivery attempt. Use this after fixing the destination endpoint or resolving the error that caused the original failure.

Example response (200):

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued"
}

Metrics & Limits

`GET /v1/metrics` — Delivery Metrics (30-day)

Returns aggregate delivery statistics for the last 30 days. Use this to monitor your webhook health at a glance — see how many events were delivered successfully, how many failed, and how many are sitting in the Dead Letter Queue.

Example response (200):

{
  "delivered": 12450,
  "failed": 23,
  "pending": 5,
  "dead_letter": 2,
  "period": "30d"
}

`GET /v1/limits` — Current Plan Limits

Returns your current plan name and all associated limits. Use this to programmatically check how many destinations you can create, your monthly event quota, payload size cap, retry count, and data retention period.

Example response (200):

{
  "plan": "pro",
  "limits": {
    "max_destinations": 25,
    "max_events_per_month": 100000,
    "max_payload_kb": 256,
    "max_attempts": 15,
    "retention_days": 90
  }
}

Error Handling

All errors follow a consistent format with a machine-readable code, a human-readable message, and a request_id for tracing:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'delivery_url' is required",
    "request_id": "req_xyz789"
  }
}

Common error codes:

Code	HTTP Status	Meaning
`VALIDATION_ERROR`	400	Invalid or missing request parameters
`MISSING_API_KEY`	401	x-rapidapi-user header not provided
`NOT_FOUND`	404	Resource does not exist or does not belong to your account
`METHOD_NOT_ALLOWED`	405	HTTP method not supported on this endpoint
`RATE_LIMIT_EXCEEDED`	429	Monthly event quota exhausted — upgrade your plan
`INTERNAL_ERROR`	500	Unexpected server error — include the request_id when contacting support

Website: hookvault.net

Support: hookvault@fastmail.com

API Overview

Pricing

Rate Limiting

Authentication

Signature Verification

Endpoints

System

GET /health — Health Check

Inbox (Public)

POST /inbox/{tenant_id}/{inbox_token} — Capture Inbound Webhook

Destinations

POST /v1/destinations — Create Destination

GET /v1/destinations — List Destinations

GET /v1/destinations/{id} — Get Destination by ID

PATCH /v1/destinations/{id} — Update Destination

DELETE /v1/destinations/{id} — Delete Destination

POST /v1/destinations/{id}/test — Send Test Payload

Events

POST /v1/events — Send Event (Push Mode)

GET /v1/events — List Events

GET /v1/events/{event_id} — Get Event by ID

GET /v1/events/{event_id}/attempts — Get Delivery Attempts

POST /v1/events/{event_id}/cancel — Cancel Pending Event

Replay

POST /v1/events/{event_id}/replay — Replay Event

Dead Letter Queue (DLQ)

GET /v1/dlq — List Dead-Lettered Events

POST /v1/dlq/{event_id}/replay — Replay from DLQ

Metrics & Limits

GET /v1/metrics — Delivery Metrics (30-day)

GET /v1/limits — Current Plan Limits

Error Handling

`GET /health` — Health Check

`POST /inbox/{tenant_id}/{inbox_token}` — Capture Inbound Webhook

`POST /v1/destinations` — Create Destination

`GET /v1/destinations` — List Destinations

`GET /v1/destinations/{id}` — Get Destination by ID

`PATCH /v1/destinations/{id}` — Update Destination

`DELETE /v1/destinations/{id}` — Delete Destination

`POST /v1/destinations/{id}/test` — Send Test Payload

`POST /v1/events` — Send Event (Push Mode)

`GET /v1/events` — List Events

`GET /v1/events/{event_id}` — Get Event by ID

`GET /v1/events/{event_id}/attempts` — Get Delivery Attempts

`POST /v1/events/{event_id}/cancel` — Cancel Pending Event

`POST /v1/events/{event_id}/replay` — Replay Event

`GET /v1/dlq` — List Dead-Lettered Events

`POST /v1/dlq/{event_id}/replay` — Replay from DLQ

`GET /v1/metrics` — Delivery Metrics (30-day)

`GET /v1/limits` — Current Plan Limits