API Reference: Complete REST API Documentation

Complete REST API reference for FetchHook webhook mailbox endpoints, authentication, and error handling.

#Base URL

All API requests use this base URL with standard REST conventions, Bearer token authentication, and JSON responses.

API Base URL

bash

https://api.fetchhook.app/api/v1

#Authentication

All requests require a Bearer token in the Authorization header. Get your API key from the dashboard after provisioning.

Authentication Header

bash

curl https://api.fetchhook.app/api/v1/{SOURCE_ID} \
  -H "Authorization: Bearer YOUR_API_KEY"

#Fetch Webhooks

Retrieve webhooks sent to your webhook URL. Use query parameters to filter by timestamp, limit results, or paginate.

Fetch All Webhooks

bash

# Fetch all webhooks
GET /api/v1/{SOURCE_ID}

# Filter by timestamp
GET /api/v1/{SOURCE_ID}?since=2024-01-15T10:00:00Z

# Limit results
GET /api/v1/{SOURCE_ID}?limit=10

# Combine filters
GET /api/v1/{SOURCE_ID}?since=2024-01-15T10:00:00Z&limit=50

Query parameters: **since** (ISO 8601 timestamp), **limit** (1-1000, default 100), **offset** (integer for pagination).

Response Format

json

{
  "webhooks": [
    {
      "event_id": "evt_1234567890abcdef",
      "provider": "stripe",
      "payload": {
        "id": "ch_3xyz",
        "object": "charge",
        "amount": 2000,
        "currency": "usd"
      },
      "headers": {
        "content-type": "application/json",
        "stripe-signature": "t=1234567890,v1=abc123..."
      },
      "received_at": "2024-01-15T14:32:15.123Z"
    }
  ],
  "count": 1,
  "has_more": false
}

#Webhook Ingestion

Your webhook URL automatically receives POST requests from external services. FetchHook captures payload, headers, and metadata.

Webhook Endpoint

bash

# External services send to your webhook URL
POST https://webhook.fetchhook.app/{SOURCE_ID}
Content-Type: application/json

{
  "event": "payment.succeeded",
  "amount": 2000
}

# Response:
{
  "status": "received",
  "webhook_id": "evt_1234567890abcdef",
  "received_at": "2024-01-15T14:32:15.123Z"
}

#Rate Limits

Webhook ingestion: 1000 req/min per source. API fetch: 100 req/min per key. Burst allowance: 2x limit for short bursts.

Rate Limit Headers

bash

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642251600

#Error Codes

Standard HTTP status codes: 200 (OK), 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 429 (rate limit), 500 (server error).

Error Response

json

{
  "error": {
    "code": "invalid_request",
    "message": "The 'since' parameter must be a valid ISO 8601 timestamp",
    "param": "since"
  }
}

Agent Protocol Instruction

For production: Use the `since` parameter to fetch only new webhooks, implement exponential backoff for retries, store API keys in environment variables, handle pagination with `limit` and `offset`, and monitor rate limit headers to avoid throttling.