Webhooks API

Webhooks deliver real-time notifications when events occur in Rhumby. Subscribe to registration updates, result changes, and other events to keep your systems in sync.

How Webhooks Work

Create a webhook with your endpoint URL and event subscriptions
Save the signing secret (shown only once, like API keys)
Rhumby sends HTTP POST requests to your endpoint when subscribed events occur
Verify the signature using the secret to ensure authenticity
Respond with 2xx status code to acknowledge receipt

Webhook Format

All webhook payloads include:

{
  "id": "evt_msg_abc123",
  "event": "registration.created",
  "createdAt": "2026-03-29T16:00:00Z",
  "data": {
    // Event-specific payload
  }
}

Endpoints

GET/api/v1/webhooks

List webhooks for your organization

POST/api/v1/webhooks

Create a new webhook subscription

GET/api/v1/webhooks/:id

Get webhook details

PATCH/api/v1/webhooks/:id

Update webhook configuration

DELETE/api/v1/webhooks/:id

Delete a webhook subscription

All webhook endpoints require the admin scope on your API key. Only organization admins can manage webhooks.

List Webhooks

Retrieve all webhook subscriptions for your organization.

GET /api/v1/webhooks

Example Request

curl "https://rhumby.com/api/v1/webhooks" \
  -H "Authorization: Bearer rhb_sk_..."

Example Response

{
  "data": [
    {
      "id": "whk_abc123",
      "url": "https://api.yourapp.com/webhooks/rhumby",
      "events": ["registration.created", "registration.updated", "results.updated"],
      "active": true,
      "lastTriggeredAt": "2026-03-29T10:30:00Z",
      "failureCount": 0,
      "createdAt": "2026-01-15T09:00:00Z"
    },
    {
      "id": "whk_def456",
      "url": "https://discord.com/api/webhooks/123456/token",
      "events": ["results.published"],
      "active": true,
      "lastTriggeredAt": null,
      "failureCount": 0,
      "createdAt": "2026-02-20T14:00:00Z"
    }
  ]
}

Parameter	Type	Required	Description
`id`	`string`	No	Unique webhook identifier
`url`	`string`	No	Webhook endpoint URL
`events`	`array`	No	Array of subscribed event types
`active`	`boolean`	No	Whether the webhook is active
`lastTriggeredAt`	`string`	No	ISO 8601 timestamp of last successful delivery (null if never triggered)
`failureCount`	`number`	No	Consecutive failed delivery attempts. Resets on successful delivery.
`createdAt`	`string`	No	ISO 8601 timestamp of webhook creation

id

stringOptional

Unique webhook identifier

url

stringOptional

Webhook endpoint URL

events

arrayOptional

Array of subscribed event types

active

booleanOptional

Whether the webhook is active

lastTriggeredAt

stringOptional

ISO 8601 timestamp of last successful delivery (null if never triggered)

failureCount

numberOptional

Consecutive failed delivery attempts. Resets on successful delivery.

createdAt

stringOptional

ISO 8601 timestamp of webhook creation

The signing secret is never returned in list or get responses. It is shown only once during creation.

Create Webhook

Subscribe to events by creating a new webhook.

POST /api/v1/webhooks

Request Body

Parameter	Type	Required	Description
`url`	`string`	Yes	Webhook endpoint URL. Must use HTTPS in production.
`events`	`array`	Yes	Array of event types to subscribe to. Must include at least one event.

url

stringRequired

Webhook endpoint URL. Must use HTTPS in production.

events

arrayRequired

Array of event types to subscribe to. Must include at least one event.

Example Request

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

Example Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.yourapp.com/webhooks/rhumby",
    "events": ["registration.created", "registration.updated", "results.updated"],
    "active": true,
    "createdAt": "2026-03-29T16:00:00Z",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
  },
  "message": "Webhook created. Save the secret — it will not be shown again."
}

The secret is returned only in this response. Store it securely. You need it to verify webhook signatures.

Get Webhook

Retrieve details about a specific webhook. The secret is not included.

GET /api/v1/webhooks/:id

Example Request

curl "https://rhumby.com/api/v1/webhooks/whk_abc123" \
  -H "Authorization: Bearer rhb_sk_..."

Example Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.yourapp.com/webhooks/rhumby",
    "events": ["registration.created", "registration.updated", "results.updated"],
    "active": true,
    "lastTriggeredAt": "2026-03-29T10:30:00Z",
    "failureCount": 0,
    "createdAt": "2026-01-15T09:00:00Z"
  }
}

Update Webhook

Update webhook URL, events, or active status.

PATCH /api/v1/webhooks/:id

Request Body

Parameter	Type	Required	Description
`url`	`string`	No	New webhook endpoint URL (must use HTTPS in production)
`events`	`array`	No	Updated event subscription list (replaces existing events)
`active`	`boolean`	No	Enable or disable the webhook

url

stringOptional

New webhook endpoint URL (must use HTTPS in production)

events

arrayOptional

Updated event subscription list (replaces existing events)

active

booleanOptional

Enable or disable the webhook

Example Request

curl -X PATCH "https://rhumby.com/api/v1/webhooks/whk_abc123" \
  -H "Authorization: Bearer rhb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Example Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.yourapp.com/webhooks/rhumby",
    "events": ["registration.created", "registration.updated", "results.updated"],
    "active": false,
    "lastTriggeredAt": "2026-03-29T10:30:00Z",
    "failureCount": 0,
    "createdAt": "2026-01-15T09:00:00Z"
  },
  "message": "Webhook updated successfully"
}

Setting active: false pauses webhook delivery without deleting the subscription. Deliveries resume when you set it back to true.

Delete Webhook

Permanently delete a webhook subscription.

DELETE /api/v1/webhooks/:id

Example Request

curl -X DELETE "https://rhumby.com/api/v1/webhooks/whk_abc123" \
  -H "Authorization: Bearer rhb_sk_..."

Example Response

{
  "message": "Webhook deleted successfully"
}

Deleted webhooks cannot be recovered. Create a new webhook if you need to re-subscribe.

Event Types

Subscribe to any combination of these event types:

Registration Events

registration.created — New sailor registration submitted
registration.updated — Registration details changed (boat, crew, etc.)
registration.cancelled — Sailor withdrew from event

Results Events

results.updated — Race results posted or updated
results.published — Results officially published (no longer provisional)
standings.updated — Series or event standings recalculated

Event Management

event.created — New event/regatta created
event.updated — Event details changed (dates, venue, registration status)
race.scheduled — New race added to schedule
race.started — Race start time recorded
race.completed — Race finish recorded

See Webhook Delivery for detailed event payload examples.

Delivery & Retries

Timeout: Rhumby waits up to 10 seconds for a 2xx response
Retries: Failed deliveries retry up to 3 times with exponential backoff (1s, 5s, 30s)
Auto-disable: After 10 consecutive failures, webhooks are automatically deactivated
Headers: Each delivery includes:
- X-Rhumby-Signature — HMAC-SHA256 signature for verification
- X-Rhumby-Event — Event type (e.g., registration.created)
- X-Rhumby-Delivery — Unique delivery ID

Your endpoint must respond with a 2xx status code within 10 seconds. Avoid long-running processing in the webhook handler — queue jobs instead.

Signature Verification

Always verify webhook signatures to ensure requests are from Rhumby:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const expected = 'sha256=' + hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Express.js example
app.post('/webhooks/rhumby', (req, res) => {
  const signature = req.headers['x-rhumby-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook event
  const { event, data } = req.body;
  console.log('Received event:', event, data);
  
  res.status(200).send('OK');
});

See Webhook Signatures for examples in other languages.

Best Practices

Security

Always verify signatures before processing webhook data
Use HTTPS endpoints in production (enforced by the API)
Rotate secrets if compromised by deleting and recreating the webhook
Validate event types before processing to avoid unexpected events

Reliability

Respond quickly — Acknowledge receipt with 2xx immediately, then queue processing
Implement idempotency using the id field to handle duplicate deliveries
Monitor failureCount — High counts indicate endpoint issues
Use active: false to pause deliveries during maintenance instead of deleting

Development

Use webhook proxies like ngrok or webhookrelay.com for local testing
Test with real events in a staging organization before deploying to production
Log all deliveries including headers and payload for debugging

Webhook Delivery — Detailed event payload examples
Webhook Signatures — Signature verification in multiple languages
Webhooks Overview — High-level webhook concepts
API Keys — Create an API key with admin scope to manage webhooks

Webhooks API

Webhooks deliver real-time notifications when events occur in Rhumby. Subscribe to registration updates, result changes, and other events to keep your systems in sync.

How Webhooks Work

Create a webhook with your endpoint URL and event subscriptions
Save the signing secret (shown only once, like API keys)
Rhumby sends HTTP POST requests to your endpoint when subscribed events occur
Verify the signature using the secret to ensure authenticity
Respond with 2xx status code to acknowledge receipt

Webhook Format

All webhook payloads include:

{
  "id": "evt_msg_abc123",
  "event": "registration.created",
  "createdAt": "2026-03-29T16:00:00Z",
  "data": {
    // Event-specific payload
  }
}

Endpoints

GET/api/v1/webhooks

List webhooks for your organization

POST/api/v1/webhooks

Create a new webhook subscription

GET/api/v1/webhooks/:id

Get webhook details

PATCH/api/v1/webhooks/:id

Update webhook configuration

DELETE/api/v1/webhooks/:id

Delete a webhook subscription

All webhook endpoints require the admin scope on your API key. Only organization admins can manage webhooks.

List Webhooks

Retrieve all webhook subscriptions for your organization.

GET /api/v1/webhooks

Example Request

curl "https://rhumby.com/api/v1/webhooks" \
  -H "Authorization: Bearer rhb_sk_..."

Example Response

{
  "data": [
    {
      "id": "whk_abc123",
      "url": "https://api.yourapp.com/webhooks/rhumby",
      "events": ["registration.created", "registration.updated", "results.updated"],
      "active": true,
      "lastTriggeredAt": "2026-03-29T10:30:00Z",
      "failureCount": 0,
      "createdAt": "2026-01-15T09:00:00Z"
    },
    {
      "id": "whk_def456",
      "url": "https://discord.com/api/webhooks/123456/token",
      "events": ["results.published"],
      "active": true,
      "lastTriggeredAt": null,
      "failureCount": 0,
      "createdAt": "2026-02-20T14:00:00Z"
    }
  ]
}

Parameter	Type	Required	Description
`id`	`string`	No	Unique webhook identifier
`url`	`string`	No	Webhook endpoint URL
`events`	`array`	No	Array of subscribed event types
`active`	`boolean`	No	Whether the webhook is active
`lastTriggeredAt`	`string`	No	ISO 8601 timestamp of last successful delivery (null if never triggered)
`failureCount`	`number`	No	Consecutive failed delivery attempts. Resets on successful delivery.
`createdAt`	`string`	No	ISO 8601 timestamp of webhook creation

id

stringOptional

Unique webhook identifier

url

stringOptional

Webhook endpoint URL

events

arrayOptional

Array of subscribed event types

active

booleanOptional

Whether the webhook is active

lastTriggeredAt

stringOptional

ISO 8601 timestamp of last successful delivery (null if never triggered)

failureCount

numberOptional

Consecutive failed delivery attempts. Resets on successful delivery.

createdAt

stringOptional

ISO 8601 timestamp of webhook creation

The signing secret is never returned in list or get responses. It is shown only once during creation.

Create Webhook

Subscribe to events by creating a new webhook.

POST /api/v1/webhooks

Request Body

Parameter	Type	Required	Description
`url`	`string`	Yes	Webhook endpoint URL. Must use HTTPS in production.
`events`	`array`	Yes	Array of event types to subscribe to. Must include at least one event.

url

stringRequired

Webhook endpoint URL. Must use HTTPS in production.

events

arrayRequired

Array of event types to subscribe to. Must include at least one event.

Example Request

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

Example Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.yourapp.com/webhooks/rhumby",
    "events": ["registration.created", "registration.updated", "results.updated"],
    "active": true,
    "createdAt": "2026-03-29T16:00:00Z",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
  },
  "message": "Webhook created. Save the secret — it will not be shown again."
}

The secret is returned only in this response. Store it securely. You need it to verify webhook signatures.

Get Webhook

Retrieve details about a specific webhook. The secret is not included.

GET /api/v1/webhooks/:id

Example Request

curl "https://rhumby.com/api/v1/webhooks/whk_abc123" \
  -H "Authorization: Bearer rhb_sk_..."

Example Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.yourapp.com/webhooks/rhumby",
    "events": ["registration.created", "registration.updated", "results.updated"],
    "active": true,
    "lastTriggeredAt": "2026-03-29T10:30:00Z",
    "failureCount": 0,
    "createdAt": "2026-01-15T09:00:00Z"
  }
}

Update Webhook

Update webhook URL, events, or active status.

PATCH /api/v1/webhooks/:id

Request Body

Parameter	Type	Required	Description
`url`	`string`	No	New webhook endpoint URL (must use HTTPS in production)
`events`	`array`	No	Updated event subscription list (replaces existing events)
`active`	`boolean`	No	Enable or disable the webhook

url

stringOptional

New webhook endpoint URL (must use HTTPS in production)

events

arrayOptional

Updated event subscription list (replaces existing events)

active

booleanOptional

Enable or disable the webhook

Example Request

curl -X PATCH "https://rhumby.com/api/v1/webhooks/whk_abc123" \
  -H "Authorization: Bearer rhb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Example Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.yourapp.com/webhooks/rhumby",
    "events": ["registration.created", "registration.updated", "results.updated"],
    "active": false,
    "lastTriggeredAt": "2026-03-29T10:30:00Z",
    "failureCount": 0,
    "createdAt": "2026-01-15T09:00:00Z"
  },
  "message": "Webhook updated successfully"
}

Setting active: false pauses webhook delivery without deleting the subscription. Deliveries resume when you set it back to true.

Delete Webhook

Permanently delete a webhook subscription.

DELETE /api/v1/webhooks/:id

Example Request

curl -X DELETE "https://rhumby.com/api/v1/webhooks/whk_abc123" \
  -H "Authorization: Bearer rhb_sk_..."

Example Response

{
  "message": "Webhook deleted successfully"
}

Deleted webhooks cannot be recovered. Create a new webhook if you need to re-subscribe.

Event Types

Subscribe to any combination of these event types:

Registration Events

registration.created — New sailor registration submitted
registration.updated — Registration details changed (boat, crew, etc.)
registration.cancelled — Sailor withdrew from event

Results Events

results.updated — Race results posted or updated
results.published — Results officially published (no longer provisional)
standings.updated — Series or event standings recalculated

Event Management

event.created — New event/regatta created
event.updated — Event details changed (dates, venue, registration status)
race.scheduled — New race added to schedule
race.started — Race start time recorded
race.completed — Race finish recorded

See Webhook Delivery for detailed event payload examples.

Delivery & Retries

Timeout: Rhumby waits up to 10 seconds for a 2xx response
Retries: Failed deliveries retry up to 3 times with exponential backoff (1s, 5s, 30s)
Auto-disable: After 10 consecutive failures, webhooks are automatically deactivated
Headers: Each delivery includes:
- X-Rhumby-Signature — HMAC-SHA256 signature for verification
- X-Rhumby-Event — Event type (e.g., registration.created)
- X-Rhumby-Delivery — Unique delivery ID

Your endpoint must respond with a 2xx status code within 10 seconds. Avoid long-running processing in the webhook handler — queue jobs instead.

Signature Verification

Always verify webhook signatures to ensure requests are from Rhumby:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const expected = 'sha256=' + hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Express.js example
app.post('/webhooks/rhumby', (req, res) => {
  const signature = req.headers['x-rhumby-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook event
  const { event, data } = req.body;
  console.log('Received event:', event, data);
  
  res.status(200).send('OK');
});

See Webhook Signatures for examples in other languages.

Best Practices

Security

Always verify signatures before processing webhook data
Use HTTPS endpoints in production (enforced by the API)
Rotate secrets if compromised by deleting and recreating the webhook
Validate event types before processing to avoid unexpected events

Reliability

Respond quickly — Acknowledge receipt with 2xx immediately, then queue processing
Implement idempotency using the id field to handle duplicate deliveries
Monitor failureCount — High counts indicate endpoint issues
Use active: false to pause deliveries during maintenance instead of deleting

Development

Use webhook proxies like ngrok or webhookrelay.com for local testing
Test with real events in a staging organization before deploying to production
Log all deliveries including headers and payload for debugging

Webhook Delivery — Detailed event payload examples
Webhook Signatures — Signature verification in multiple languages
Webhooks Overview — High-level webhook concepts
API Keys — Create an API key with admin scope to manage webhooks

Webhooks API

On this page

Webhooks API

On this page