Verify OneLifeVibe webhooks in Ruby

What you are building

The recipe is one function, verify_onelifevibe, that takes the raw request body, the two signing headers, your endpoint secret and an optional tolerance. It checks the timestamp, recomputes the expected signature, compares the two in constant time, and returns the parsed event only when both checks pass. Anything else raises, so your Rack handler can answer with a non-2xx status instead of acting on an unverified payload.

It fits a Sinatra route, a Rails controller or plain Rack middleware, because it assumes nothing beyond the request body and the env hash. The comments at the bottom of the page show the wiring: request.body.read gives you the raw body, and header names arrive uppercased with an HTTP_ prefix.

Before you start

You need the endpoint secret from the moment the subscription is created, because the secret is returned once and never shown again. Store it outside your repository, for example in the environment variable OLV_WEBHOOK_SECRET that the snippet reads, and use a separate secret per environment.

Webhooks require a paid plan: Starter at $19 per month or $199 per year. On the free Sandbox you do not receive deliveries; poll GET /api/platform/v1/events instead.

In Rack the headers do not arrive under their literal names. Read webhook-id, webhook-timestamp and webhook-signature from HTTP_WEBHOOK_ID, HTTP_WEBHOOK_TIMESTAMP and HTTP_WEBHOOK_SIGNATURE in request.env.

How the code works

The first step reads webhook-timestamp, converts it with to_i and rejects anything more than 300 seconds away from Time.now.to_i. That is the default tolerance, and it is worth leaving alone: a wider window gives a captured request more time to be replayed.

The signed string is the timestamp, a literal dot, then the raw body exactly as it arrived, meaning the bytes you received before JSON parsing touches them. OpenSSL::HMAC.hexdigest with the SHA256 digest and your secret as UTF-8 text produces lowercase hex, and the code prefixes that with v1= to match the header format.

The comparison is guarded by a bytesize check and then OpenSSL.fixed_length_secure_compare, so a wrong signature fails without leaking timing through an early return. Only after that does JSON.parse run, which means a forged body never reaches your parser.

Testing it

Post a request with a signature you computed yourself, then re-post it with an old webhook-timestamp to confirm the timestamp branch fires. Change one character of the body and confirm the signature check fires. Drop the v1= prefix and confirm that fails too, since a bare hex digest will never match expected.

Inspect the parsed event for the shape you expect: id, type, world, subject, origin, created_at, data and delivery, where delivery carries endpoint_id and attempts. Assert on webhook-id, which is the event id, because you need it for deduplication later.

Your endpoint must return a 2xx quickly. Anything else counts as a failure and triggers retries after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours, six attempts in total, after which the delivery is dead. Requests time out after 10 seconds and redirects are never followed, so return the status directly.

Going to production

Delivery is at-least-once, so persist webhook-id and skip any event you have already processed. Verify and dedupe inline, then hand the parsed event to a background queue and answer 2xx; slow work does not belong in the request.

Log webhook-id, the x-olv-event and x-olv-world headers and the failure reason for every rejected delivery, so you can tell a bad secret from a stale timestamp. Recreating a subscription gives you a new secret, and the old one stops matching.

Keep the raw body capture in place. Middleware that parses JSON before verification runs changes the bytes and produces a mismatch that looks like a secret problem but is not.