Webhooks

Webhooks let you receive real-time HTTP notifications when events occur in Rhumby. Instead of polling the API, register a URL and we'll POST data to it.

How it works

1. You register a webhook URL for your organization
2. You select which event types you want to receive
3. When something happens (results published, registration created, etc.), we send a POST request to your URL
4. Your server processes the payload and returns a 200 status

Event types

Payload format

All webhook payloads follow this structure:

{
  "id": "wh_evt_abc123",
  "type": "results.published",
  "timestamp": "2026-03-29T18:30:00Z",
  "organization": {
    "id": "org_123",
    "slug": "sarasota-sailing-squadron"
  },
  "data": {
    "eventSlug": "friday-night-spring-2026",
    "raceId": "race_456",
    "raceNumber": 5,
    "fleetName": "PHRF Spinnaker",
    "resultsCount": 9
  }
}

Failure Handling

Rhumby delivers each webhook event once with a 5-second timeout. If your endpoint:

• Returns a non-2xx status code
• Times out (>5 seconds)
• Fails to connect

...the delivery is considered failed and the webhook's consecutive failure count increments.

After 10 consecutive failures, the webhook is automatically deactivated. You can reactivate it from the dashboard. On successful delivery, the failure count resets to 0.

Note: Automatic retry support (exponential backoff) is planned for a future release. For now, ensure your endpoint returns 200 quickly (within 5 seconds) and processes events asynchronously if needed.

Setting up a webhook

curl -X POST https://rhumby.com/api/v1/webhooks \
  -H "Authorization: Bearer rhb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/rhumby",
    "events": ["results.published", "registration.created"]
  }'