API Reference

webhook.rodeo provides a simple HTTP API for receiving webhooks. This reference covers everything you need to know about sending webhooks to your endpoints.

Webhook endpoint

Every webhook you create gets a unique URL:

POST https://webhook.rodeo/w/{username}/{webhook-name}

Path parameters

• username - Your webhook.rodeo username (lowercase)
• webhook-name - The name of your webhook (lowercase with hyphens)

Example

If your username is sarah and you created a webhook named github-webhooks:

POST https://webhook.rodeo/w/sarah/github-webhooks

Request format

HTTP method

Only POST requests are accepted. Other methods return 405 Method Not Allowed.

Headers

Required headers

Content-Type: application/json

While not strictly enforced, we recommend always including Content-Type to indicate your payload format.

Optional headers

X-Rodeo-Signature: a1b2c3d4e5f6...

Include this header if you've configured a secret on your webhook. The signature should be a hex-encoded HMAC-SHA256 hash of the request body.

Preserved headers

All headers you send are captured and forwarded (except Host and Connection which are modified for forwarding).

Body

The request body can be:

• JSON (most common)
• XML
• Form data (application/x-www-form-urlencoded)
• Plain text
• Binary data

Maximum body size: 4.5MB

Example request

curl -X POST https://webhook.rodeo/w/sarah/github-webhooks \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-GitHub-Delivery: 12345678-1234-1234-1234-123456789012" \
  -H "X-Rodeo-Signature: a1b2c3d4..." \
  -d '{
    "ref": "refs/heads/main",
    "repository": {
      "name": "my-app",
      "full_name": "sarah/my-app"
    },
    "commits": [...]
  }'

Response format

Success response

When a webhook is received successfully:

{
  "success": true,
  "requestId": "req_2gKp7vXm9nQ1rL3sT8wY"
}

Status code: 200 OK

The requestId is a unique identifier you can use to track this specific event through the system.

Response timing

webhook.rodeo responds immediately (usually under 50ms) without waiting for forwarding to complete. This ensures webhook senders don't time out while we process and forward your event.

Forwarding happens asynchronously in the background using our durable workflow system.

Status codes

webhook.rodeo returns these HTTP status codes:

Success codes

Client error codes

Server error codes

Error responses

When an error occurs, you'll receive a JSON response with details:

Rate limit exceeded

{
  "error": "Rate limit exceeded",
  "limit": "10 requests per minute",
  "plan": "free",
  "retryAfter": 30
}

Status: 429 Too Many Requests

Wait for the retryAfter seconds before trying again.

Payload too large

{
  "error": "Payload too large",
  "limit": "4.5MB",
  "received": "5.2MB"
}

Status: 413 Payload Too Large

Reduce your payload size or split it into multiple webhooks.

Signature verification failed

{
  "error": "Invalid signature",
  "message": "Signature verification failed"
}

Status: 401 Unauthorized

Check that:

• Your secret matches what's configured in webhook.rodeo
• You're computing the HMAC correctly
• The signature header is formatted correctly

Webhook not found

{
  "error": "Webhook not found",
  "username": "sarah",
  "webhookName": "nonexistent-webhook"
}

Status: 404 Not Found

Double-check the username and webhook name in your URL.

Webhook inactive

{
  "error": "Webhook is not active",
  "message": "This webhook has been deactivated"
}

Status: 403 Forbidden

Activate the webhook in your dashboard before sending events to it.

Testing your integration

Using curl

Basic test:

curl -X POST https://webhook.rodeo/w/your-username/test-webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

With signature:

SECRET="your-secret"
PAYLOAD='{"test": true}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" -hex | cut -d' ' -f2)

curl -X POST https://webhook.rodeo/w/your-username/test-webhook \
  -H "Content-Type: application/json" \
  -H "X-Rodeo-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Using webhook testing tools

Popular webhook testing tools work great with webhook.rodeo:

• Postman
• Insomnia
• HTTPie
• webhook.site (for testing your forward URL)