Set Up or Change User Events

PUT /v1/endpoints/{uuid}/user-events

Set up the endpoint's one user-events webhook, or change its address or events. ngris sends each event as a POST to the address, signed in the Standard Webhooks format (headers webhook-id, webhook-timestamp, webhook-signature). Setting it up answers 201 with the signing secret (webhook.secret, whsec_…) once: keep it, it is never shown again. A new address starts afresh: a pause ends and the events waiting are sent to it.

Path parameters

uuid string (uuid) Req
The endpoint's uuid from /endpoints.

Request body

url string Req
Your app's public https:// address (at most 2048 characters, no user name or password in it). The shortened address an answer shows keeps the saved one.
events array of strings
Any of user.created, user.updated, user.deactivated, user.deleted, user.roles_changed, user.signed_in. Left out on a new webhook: every one but user.signed_in; on a change: the saved list.

Response (201 Created, or 200 OK on a change)

The webhook and its state, as GET .../user-events answers it; with the secret when it was just made.

Errors

400 Bad Request
A field the API doesn't know; a url that isn't a public https:// address; an unknown event.
401 Unauthorized
Missing auth.
403 Forbidden
Your role lacks endpoints:update in the active account, or your plan doesn't have user events ("code": "entitlement_required", "entitlement_required": "endpoint_user_events").
404 Not Found
No such endpoint in your active account.
409 Conflict
The endpoint is paused over your plan's quota ("code": "quota_paused").
503 Service Unavailable
User events aren't available yet.
Request
curl -X PUT "https://api.ngris.com/v1/endpoints/019bb1e4-e785-77d2-9966-c3cff31d0a0e/user-events" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{"url": "https://app.acme.com/hooks/ngris"}'
CLI
ngris api endpoint-user-events set 019bb1e4-e785-77d2-9966-c3cff31d0a0e --url https://app.acme.com/hooks/ngris --yes
Response — 201 Created, or 200 OK on a change
{ "endpoint_id": "019bb1e4-e785-77d2-9966-c3cff31d0a0e", "available": true, "webhook": { "url": "https://…acme.com/…", "events": [ "user.created", "user.updated", "user.deactivated", "user.deleted", "user.roles_changed" ], "status": "active", "paused_at": null, "failing_since": null, "last_success_at": null, "created_at": "2026-11-19T14:02:11Z", "updated_at": "2026-11-19T14:02:11Z", "secret": "whsec_Tq3mH8x2Vb7Lr9nK4pZc6Ye1Wd5Ua0Sf" }, "receiver": { "on_this_endpoint": true, "sign_in_on": true, "path": "/hooks/ngris", "let_in": false, "open": false }, "event_types": [ "user.created", "user.updated", "user.deactivated", "user.deleted", "user.roles_changed", "user.signed_in" ], "default_events": [ "user.created", "user.updated", "user.deactivated", "user.deleted", "user.roles_changed" ] }
Was this helpful?
Was this helpful?