Webhooks API

Verify inbound webhook signatures (Standard Webhooks / HMAC-SHA256) and parse events into typed values. This is an inbound utility with no provider endpoint — HMAC is built on the SHA standard library. OpenAI webhooks.

Types and Constants

UniLM.WebhookEvent — Type

WebhookEvent

A parsed webhook event from parse_webhook: id, type, and created_at; data holds the event payload and raw the unparsed JSON response.

source

UniLM.WEBHOOK_EVENTS — Constant

Known OpenAI webhook event types.

source

Functions

UniLM.verify_webhook — Function

verify_webhook(payload::AbstractString, headers, secret::AbstractString; tolerance_seconds=300) -> Bool

Verify an OpenAI webhook signature (Standard Webhooks). payload is the raw request body; headers is a Dict or iterable of pairs containing webhook-id, webhook-timestamp, and webhook-signature; secret is the endpoint signing secret (with or without the whsec_ prefix). Returns true iff a fresh, validly-signed v1 signature is present.

Replay protection: timestamps outside ±tolerance_seconds of now are rejected, as are timestamps that are not finite numbers — pass tolerance_seconds=Inf to skip the time check (e.g. when replaying a stored fixture). Uses a constant-time digest compare. Negative or NaN tolerances throw ArgumentError.

Throws ArgumentError when secret is not valid base64: that is a misconfiguration of this endpoint, and reporting it as an unverified signature would silently drop every webhook. A false return therefore always means the message failed verification.

source

UniLM.parse_webhook — Function

parse_webhook(payload::AbstractString) -> WebhookEvent

Parse a webhook JSON payload into a typed WebhookEvent. Verify the signature with verify_webhook first.

source

Usage

# Verify an inbound webhook, then parse it into a typed event
if verify_webhook(payload, headers, ENV["OPENAI_WEBHOOK_SECRET"])
    event = parse_webhook(payload)
    event.type in WEBHOOK_EVENTS && println("Event: ", event.type, " (", event.id, ")")
end