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.
List endpoints and events
Section titled “List endpoints and events”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" ]}Create an endpoint
Section titled “Create an endpoint”| 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. |
Change an endpoint
Section titled “Change an endpoint”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.
Roll the secret
Section titled “Roll the secret”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 an endpoint
Section titled “Delete an endpoint”Answers 204. Deliveries not sent yet go with it.
Read the delivery log
Section titled “Read the delivery log”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.