Skip to content

Webhooks

An environment’s webhook endpoints are told what happens to its users. This page is about managing them; Webhooks explains what a delivery looks like and how to verify it.

The endpoint object:

Field Type Meaning
id uuid
url string Where deliveries are posted.
events string[] The events it receives, or ["*"] for every event, those added later included.
created_at string
created_by object or null The developer who made it (or for whom Seek made it): { "id", "email" }. null for one an API key or the suite’s setup made, and for endpoints made before 2026-11-17.
changed_by object or null Who last changed its address, events or secret, in the same shape.
changed_at string or null When.

An endpoint receives every user’s address and logins, and goes on receiving them after the person who made it has left the workspace. So making one, changing its address and rolling its secret take the admin role, and an API key cannot do them; changing which events it gets and deleting it are a developer’s. Check the list from time to time for endpoints nobody on the team owns any more.

GET/v1/environments/:id/webhooksviewer

The environment’s endpoints, and the catalogue of events an endpoint can ask for. Secrets are never listed.

{
"endpoints": [{ "id": "…", "url": "https://hooks.your-app.com/seekauth", "events": ["user.created"], "created_at": "…" }],
"events": [
"user.created", "user.updated", "user.deleted", "user.disabled", "user.enabled",
"app_user.joined", "session.revoked", "login.succeeded", "login.failed",
"mfa.enrolled", "mfa.removed", "identity.linked", "identity.unlinked",
"password.changed", "email.changed"
]
}
POST/v1/environments/:id/webhooksadmin
Field Type Meaning
url string An https address with a public host name (not an IP address), no user name or password, no fragment, up to 500 characters.
events string[] At least one event from the catalogue, or *. Repeats are dropped.

The answer has the endpoint and its signing secret, whsec_…, which is shown only here. SeekAuth keeps it encrypted.

POST /v1/environments/{env}/webhooks
{ "url": "https://hooks.your-app.com/seekauth", "events": ["user.created", "user.updated", "app_user.joined", "user.created"] }
201
{
"id": "…",
"url": "https://hooks.your-app.com/seekauth",
"events": ["user.created", "user.updated", "app_user.joined"],
"created_at": "…",
"secret": "whsec_…"
}
Status code When
400 bad_request “url must be an https address with a public host name”, “{event} is not an event”, “name at least one event, or * for all”
402 plan_limit The environment has as many endpoints as the plan includes: 1 on Free, 10 on Pro, 25 on Scale.
403 forbidden The caller is not an admin or owner of the workspace, or is an API key.
PATCH/v1/environments/:id/webhooks/:endpointdeveloper

The same body as for creating one; both url and events are required. The answer is the endpoint, or 404. Changing events is a developer’s; a url other than the endpoint’s own takes the admin role, and an API key gets 403 for it.

POST/v1/environments/:id/webhooks/:endpoint/secretadmin

Makes a new secret, shown once in the answer (the endpoint plus secret). The old one stops signing at once, so put the new one in your receiver right away.

DELETE/v1/environments/:id/webhooks/:endpointdeveloper

Answers 204. Deliveries not sent yet go with it.

GET/v1/environments/:id/webhooks/:endpoint/deliveriesviewer

The endpoint’s 50 newest deliveries.

{
"deliveries": [
{
"id": "evt_…",
"event": "user.created",
"status": "delivered",
"attempts": 1,
"response_status": 200,
"created_at": "…",
"delivered_at": "…",
"next_attempt_at": null
}
]
}
status Meaning
pending Not sent yet, or refused and waiting for next_attempt_at.
delivered Your endpoint answered with a 2xx status.
failed Given up on, after 7 tries or 18 hours.

id is the webhook-id the delivery carried. There is no route that sends a test delivery: create a user in a development environment to see one.