Build a Reliable Webhook Receiver - Ruba Docs

The delivery view records past attempts, request payloads, failure details, and manual redelivery. Your receiver still needs to preserve the raw body, verify the signature, queue durable work, and return success quickly.

Receiver sequence

Ruba request → raw body + headers → signature verification → durable queue → 2xx response

Verify with an SDK

Set RUBA_WEBHOOK_SECRET to the endpoint secret. Reject verification failures and acknowledge accepted events with a 2xx response.

import express, { Request, Response } from 'express'
import { validateEvent, WebhookVerificationError } from '@getruba/sdk/webhooks'

const app = express()

app.post('/webhook', express.raw({ type: 'application/json' }), (req: Request, res: Response) => {
  try {
    const event = validateEvent(
      req.body,
      req.headers,
      process.env['RUBA_WEBHOOK_SECRET'] ?? '',
    )

    // Queue event for processing.
    res.status(202).send('')
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return res.status(403).send('')
    }
    throw error
  }
})

import os
from flask import Flask, request
from ruba.webhooks import validate_event, WebhookVerificationError

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    try:
        event = validate_event(
            body=request.data,
            headers=request.headers,
            secret=os.getenv('RUBA_WEBHOOK_SECRET', ''),
        )
        # Queue event for processing.
        return "", 202
    except WebhookVerificationError:
        return "", 403

Verify without a Ruba SDK

Ruba follows Standard Webhooks. Use an available language library or implement the specification. A manual implementation must base64-encode the endpoint secret before signature generation; Ruba SDK helpers handle that detail.

Delivery contract

Condition	Ruba behavior	Receiver design
Network error or non-success response	Up to 10 attempts with exponential backoff	Make processing idempotent
No response within 10 seconds	Attempt is timed out and retried	Queue work and answer within 2 seconds
10 consecutive non-2xx deliveries	Endpoint is disabled and an organization admin is emailed	Fix it, then re-enable it in webhook settings
3xx response	Treated as failure; redirects are not followed	Register the final URL

Diagnose a missing event

Confirm the delivery appears in Ruba and inspect its status and payload.
During local work, confirm the tunnel is running.
Log entry, verification start, verification success, and queue insertion separately.
Send curl -vvv -X POST <endpoint> to expose a missing route or redirect. Some frameworks distinguish /foo from /foo/.
Exclude the public webhook route from login middleware.

For a 403, inspect reverse-proxy and firewall logs and make sure automated POST requests can reach the receiver. For signature errors, verify that the exact raw request body is used and that a custom implementation base64-encodes the secret.