User events
User events
When an endpoint asks people to sign in, ngris keeps its users: the people you add, invite or let sign up. User events tell your app when one of them changes, so your app's own records stay in step: a user created, changed, deactivated, deleted, given other roles, or signing in.
ngris sends each event as an HTTPS POST to one address of your app, signed so your app knows it came from ngris. Set it up in the endpoint's Sign-in & access tab, section Your app, card User events, or with the API (PUT /v1/endpoints/{uuid}/user-events).
- Type your app's
https://address and pick the events. Every event but sign-ins is ticked; sign-ins can be many on a busy site. - Click Turn on user events. Copy the signing secret it shows (
whsec_…): it isn't shown again. - In your app, check each event's signature with that secret (below), then act on it.
- Click Send a test event to see what your app answers.
User events are an endpoint feature of every plan; an admin can set it per plan. Without it, events wait and nothing is sent.
The events
| Type | Sent when |
|---|---|
user.created | A user is added, invited, signs up, or joins through single sign-on or SAML. |
user.updated | Their email, name, username, custom fields or status change, their email is confirmed, an invite is accepted, or they are paused or resumed over your plan's user limit ("paused"). changes says what changed, from and to. |
user.deactivated | Their status becomes disabled or revoked. Turning them back on is a user.updated. |
user.deleted | The user is deleted, or an open invite is cancelled. The event shows them as they were. |
user.roles_changed | They get or lose a role: by you, by sign-up, by their identity provider's groups, or when a role they hold is renamed or deleted. changes.roles lists the roles added and removed. |
user.signed_in | They sign in to a browser, any way. sign_in says how: method (password, sso, passkey or email_code), the provider for single sign-on (its id), the ip and the user_agent. A token or a password sent with each request isn't a sign-in, and a signed-in browser's later visits aren't either. Off unless you tick it. |
- An event can arrive twice (a retry after your app answered too late): keep the event
idand skip one you have seen. - Events can arrive out of order, when one is retried or when several go at once (up to 4 at a time per endpoint): each carries
created_at, the moment of the change. - A user you add gets the role new users get right after: that arrives as
user.created, thenuser.roles_changed. - Only changes after you turn events on are sent; existing users aren't sent at the start.
- Users the ngris agent makes (
ngris http --basic-auth) send no events. Deleting the endpoint or your account sends none either. - A password change, a new second step or signing out sends no event: they change nothing an event shows.
What an event carries
The user as they are at the change, never a password, a code, a secret or a session. metadata is the custom fields you set on them.
{
"id": "evt_0193f0b0aa017a008b0000000000a001",
"type": "user.roles_changed",
"created_at": "2026-11-19T15:44:20.117Z",
"endpoint": { "id": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "host": "app.acme.com" },
"user": {
"id": "0193f0b0-6666-7a00-8b00-000000000071",
"email": "maria@acme.com",
"email_confirmed": true,
"name": "Maria",
"username": "maria",
"status": "active",
"paused": false,
"roles": ["editor"],
"metadata": { "plan": "pro" },
"created_at": "2026-11-02T09:12:00Z",
"updated_at": "2026-11-19T15:44:20Z"
},
"changes": { "roles": { "added": ["editor"], "removed": ["viewer"] } }
}
Check the signature
Every event comes in the Standard Webhooks format, with three headers:
webhook-id: the event's id, the same on every retry.webhook-timestamp: when this attempt was sent, in seconds.webhook-signature:v1,and the base64 HMAC-SHA256 ofid.timestamp.body, keyed by the secret's bytes (the base64 afterwhsec_). While a new secret is a day old, two signatures come, space-separated: accept either.
Refuse an event whose timestamp is more than 5 minutes away from now (a replay), then compare the signature on the raw body, before parsing it. The standardwebhooks library does all of this in Node, Python, Go, Ruby, PHP and more; the code below does it with the standard library.
// Node.js (Express: app.post('/hooks/ngris', express.raw({ type: 'application/json' }), …))
import crypto from 'node:crypto';
export function ngrisEvent(secret, headers, rawBody) {
const id = headers['webhook-id'], ts = headers['webhook-timestamp'];
if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) throw new Error('stale or missing');
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest();
const ok = (headers['webhook-signature'] || '').split(' ').some((s) => {
const [v, sig] = s.split(',');
const got = Buffer.from(sig || '', 'base64');
return v === 'v1' && got.length === want.length && crypto.timingSafeEqual(got, want);
});
if (!ok) throw new Error('bad signature');
return JSON.parse(rawBody);
}
# Python
import base64, hashlib, hmac, json, time
def ngris_event(secret, headers, raw_body: bytes):
msg_id, ts = headers.get("webhook-id"), headers.get("webhook-timestamp")
if not msg_id or not ts or abs(time.time() - int(ts)) > 300:
raise ValueError("stale or missing")
key = base64.b64decode(secret.removeprefix("whsec_"))
want = hmac.new(key, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).digest()
for s in headers.get("webhook-signature", "").split():
v, _, sig = s.partition(",")
if v == "v1" and hmac.compare_digest(base64.b64decode(sig), want):
return json.loads(raw_body)
raise ValueError("bad signature")
// Go
func ngrisEvent(secret string, h http.Header, body []byte) error {
id, ts := h.Get("webhook-id"), h.Get("webhook-timestamp")
sec, err := strconv.ParseInt(ts, 10, 64)
if id == "" || err != nil || math.Abs(float64(time.Now().Unix()-sec)) > 300 {
return errors.New("stale or missing")
}
key, _ := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
m := hmac.New(sha256.New, key)
m.Write([]byte(id + "." + ts + "."))
m.Write(body)
want := m.Sum(nil)
for _, s := range strings.Fields(h.Get("webhook-signature")) {
if v, sig, _ := strings.Cut(s, ","); v == "v1" {
if got, _ := base64.StdEncoding.DecodeString(sig); hmac.Equal(got, want) {
return nil
}
}
}
return errors.New("bad signature")
}
Answer with any 2xx within 10 seconds once you have the event; do slow work afterwards.
An address behind sign-in
Your app usually sits behind the same endpoint, and the endpoint asks people to sign in: an event sent there would get the sign-in page. When the address is on this endpoint, the card offers Let ngris user events in on /your/path. One click lists that path as open for POST with the ngris user events signature check: ngris checks each event's signature with this endpoint's secret before it reaches your app, and anyone else on that path still has to sign in. After a new secret both work there for a day, as they sign.
The same check can be added by hand under Sign-in › Paths that skip sign-in (provider ngris-events, no secret), or with POST /v1/endpoints/{uuid}/access-paths. An address on another host, or another endpoint, isn't checked by ngris: check the signature in your app there.
Deliveries, retries and pausing
- An event goes only to a public
https://address. A redirect isn't followed, and only a2xxanswer within 10 seconds counts as delivered. - A failed delivery is tried again after 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 8 hours and 8 hours: about a day, 9 attempts in all. Then the event shows as failed.
- When every delivery failed for 5 days, the events pause and the account owner gets an email. New events wait 7 days; click Turn back on (or change the address) and what waited is sent.
- The card's Deliveries list shows each event, its user, and whether it was delivered, is being retried, or failed, with your app's answer. Resend sends a delivered or failed event again. The list keeps 14 days.
- Send a test event sends an example (type
webhook.test, an example user) at once and shows your app's answer. It isn't kept in the list.
A new signing secret
New secret makes a new secret and shows it once. For a day, every event is signed with both the new and the old secret, so your app can switch to the new one without missing an event.
If the old secret leaked, tick Stop the old secret now (in the API, "end_previous_now": true): events are signed with the new one alone, and the path check above stops accepting the old one. Events your app checks with the old secret fail until it has the new one; they are retried.
The address works like a password too (it may carry a token): the dashboard and the API show it shortened, and keeping the shortened value keeps the saved address.
In the API, CLI and MCP
Everything the card does, the API does under /v1/endpoints/{uuid}/user-events (API docs pages), the CLI under ngris api endpoint-user-events, and the MCP server's endpoint tools.