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 & Size Constraints

Rate limits per IP address: Webhook ingestion 1000/hour, API fetch 100/minute, Provision 1000/hour. Payload size limit: 1MB per webhook. Exceeding limits returns 429 (rate limit) or 413 (payload too large).

Rate Limits

bash

# Webhook Ingestion: 1000 requests per hour per IP
POST /in/{SOURCE_ID}

# API Fetch: 100 requests per minute per IP
GET /api/v1/{SOURCE_ID}

# Provision: 1000 requests per hour per IP
POST /provision

# Admin Endpoints: 60 requests per minute per IP
GET /admin/usage/{TENANT_ID}

# Payload Size: Maximum 1MB (1,048,576 bytes)
# Exceeds limit: 413 Payload Too Large

#Error Codes

Standard HTTP status codes: 200 (OK), 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 413 (payload too large), 429 (rate limit exceeded), 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.