Skip to content

Webhooks

A webhook endpoint is an address of your server that SeekAuth tells what happens to the users of an environment: a sign-up, a login, a changed address, a deleted account. Deliveries are signed as the Standard Webhooks specification says, retried for hours when your server does not answer, and kept in a log you can read.

Event When
user.created Someone signed up.
user.updated A name, picture or email address changed.
user.deleted An account was deleted, by the user (data.by is user) or an admin. Delete what you keep about them.
user.disabled An account was disabled.
user.enabled A disabled account was enabled again.
app_user.joined A user entered an app for the first time.
session.revoked A session ended: a logout, or a revocation.
login.succeeded A user logged in.
login.failed A login attempt was refused.
mfa.enrolled A second factor was added, or new recovery codes were made.
mfa.removed A second factor was removed.
identity.linked Another way to log in was connected, such as Google or a wallet.
identity.unlinked A way to log in was removed.
password.changed A password was set or changed.
email.changed A new email address. It is also sent as user.updated.

* subscribes to every event, those added later included. Changes made by your team (settings, clients, roles) are in the audit log, not sent as webhooks. An event is sent if and only if it was recorded in the audit log.

On the Webhooks page, or with the management API, as an admin or owner of the workspace (an endpoint receives every user’s address and logins, so naming one is not a developer’s or an API key’s to do):

POST/v1/environments/:id/webhooksadmin
{ "url": "https://api.your-app.com/webhooks/seekauth", "events": ["user.created", "user.deleted", "user.disabled"] }
{
"id": "…",
"url": "https://api.your-app.com/webhooks/seekauth",
"events": ["user.created", "user.deleted", "user.disabled"],
"created_at": "…",
"secret": "whsec_…"
}

The address is https, with a public host name (not an IP address), at most 500 characters. The secret is shown here once; keep it in your server’s secrets. Each environment has its own endpoints: the Free plan includes 1 per environment, Pro 10, Scale 25. See Webhooks in the management API.

A POST with a JSON body:

{
"id": "evt_5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
"type": "user.created",
"created": 1791460990,
"environment_id": "<environment id>",
"app_id": "<app id>",
"user_id": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10",
"actor_user_id": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10",
"user": {
"id": "0b9f6c1e-4d7a-4c55-9a1e-2f3b8d6c7e10",
"email": "[email protected]",
"email_verified": true,
"name": "Ada Lovelace",
"picture": null,
"status": "active"
},
"data": { "method": "email_code" }
}
Field Meaning
id The delivery’s id, the same as the webhook-id header. Each endpoint gets its own id for the same event.
type The event.
created When the event was recorded, in Unix seconds.
environment_id, app_id Where it happened. app_id is null when it belongs to no single app.
user_id The user the event is about.
actor_user_id Who did it: the user themself, or null when it was done from the dashboard or with an API key.
user The user as they are now: id, email, email_verified, name, picture, status. null for user.deleted, and in every delivery about a user once their account is deleted: the earlier ones in the log, and those still to be sent.
data What the event adds, such as the login method.

Headers:

Header Value
content-type application/json
webhook-id The delivery’s id, evt_….
webhook-timestamp When this attempt was sent, in Unix seconds. A retry has a new timestamp and the same id.
webhook-signature v1, and the base64 HMAC-SHA256 of {id}.{timestamp}.{body}.

Check every delivery before you act on it:

  1. Take the secret after whsec_ and base64-decode it: that is the key.
  2. Compute HMAC-SHA256 with the key over {webhook-id}.{webhook-timestamp}.{body}, where body is the raw request body exactly as it arrived (not re-serialised JSON).
  3. The webhook-signature header holds one or more space-separated v1,<base64> values. Accept the delivery if any of them equals your result, compared in constant time.
  4. Refuse a webhook-timestamp more than five minutes from your clock, either way, so an old delivery cannot be replayed.

auth_client::webhook::verify does all four (with a tolerance of 300 seconds):

use auth_client::webhook;
use axum::{body::Bytes, http::{HeaderMap, StatusCode}};
use std::time::{SystemTime, UNIX_EPOCH};
fn header<'a>(headers: &'a HeaderMap, name: &str) -> &'a str {
headers.get(name).and_then(|value| value.to_str().ok()).unwrap_or_default()
}
async fn seekauth_events(headers: HeaderMap, body: Bytes) -> StatusCode {
let secret = std::env::var("SEEKAUTH_WEBHOOK_SECRET").unwrap_or_default();
let now = SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_secs() as i64).unwrap_or(0);
if !webhook::verify(
&secret,
header(&headers, "webhook-id"),
header(&headers, "webhook-timestamp"),
header(&headers, "webhook-signature"),
&body,
now,
) {
return StatusCode::UNAUTHORIZED;
}
// The same webhook-id can arrive more than once: skip the ones already handled.
let event: serde_json::Value = match serde_json::from_slice(&body) {
Ok(event) => event,
Err(_) => return StatusCode::BAD_REQUEST,
};
// ... handle event["type"] ...
StatusCode::NO_CONTENT
}

With node:crypto and nothing else; here in an Express route that keeps the raw body:

import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'
const TOLERANCE_SECONDS = 300
export function verifyWebhook(secret, headers, rawBody) {
const id = headers['webhook-id']
const timestamp = headers['webhook-timestamp']
const signatures = headers['webhook-signature']
if (!id || !timestamp || !signatures) return false
const sentAt = Number(timestamp)
if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > TOLERANCE_SECONDS) return false
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
if (key.length === 0) return false
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest()
return signatures.split(' ').some((candidate) => {
const [version, value] = candidate.split(',', 2)
if (version !== 'v1' || !value) return false
const given = Buffer.from(value, 'base64')
return given.length === expected.length && timingSafeEqual(given, expected)
})
}
const app = express()
app.post('/webhooks/seekauth', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyWebhook(process.env.SEEKAUTH_WEBHOOK_SECRET, req.headers, req.body)) {
return res.sendStatus(401)
}
const event = JSON.parse(req.body.toString('utf8'))
// The same event.id can arrive more than once: skip the ones already handled.
res.sendStatus(204)
})

Any Standard Webhooks library does the same.

  • Success is an answer with a 2xx status within 5 seconds. Redirects are not followed: a 3xx counts as a failure.
  • Retries: a delivery that fails is tried again after 1, 5 and 30 minutes, then 2, 5 and 10 hours: seven tries in all, and never once it is 18 hours old. Then it is given up on.
  • At least once. The same delivery can arrive more than once. Remember the webhook-ids you handled and skip repeats.
  • Order. An endpoint gets one delivery at a time, in the order the events happened, while it takes them. One it refuses waits for its retry while the ones after it go on, so order by created where it matters.
  • Pausing. Three bad sends in a row (failures, or answers slower than 3 seconds) pause the endpoint for 5 minutes, doubling with each further one up to an hour. One good answer ends the pause. Answer quickly and do the work afterwards.
  • Deliveries go to https addresses with a public host name, on port 443 or 8443, and to public addresses only. Verify the signature rather than trusting a source address.

The Webhooks page shows each endpoint’s last 50 deliveries: delivered, pending (not sent yet, or refused and waiting for its next try) or failed, with the attempts and your server’s status. The same is GET /v1/environments/:id/webhooks/:endpoint/deliveries. Deliveries are kept 30 days.

Make a new secret on the Webhooks page, or with POST /v1/environments/:id/webhooks/:endpoint/secret. It is shown once, and the old secret stops signing at once, so put the new one in your server straight away; a delivery your server refuses in between is tried again later.

A web client’s backend keeps sessions of its own. When user.deleted or user.disabled arrives, end them with WebClient::end_sessions_of(user_id); see Sessions and sign-out.