Documentation
Webhooks
Webhooks send Halo's audit and sign-in events to your own HTTPS endpoint as they happen, so a SIEM, a chat channel or an internal tool can react to them. Each request is signed with a secret only you and Halo know.
Security administrators manage webhook endpoints; every administrator can read them and their delivery logs.
Events
Every event has the same envelope: an id, a type, the time it happened, and data with the event itself. There are two sources, with two shapes of data.
Audit events. The type is the audit action, such as user.invite, group.member.add or policy.update, and data is the audit event: id, time, actorId (null for changes Halo made itself, such as lifecycle rules and expiring grants), action, summary, targetType, targetId, target (the target's name when the change happened) and ip.
{
"id": "aud_01JA2X5Q6R7S8T9V0W1X2Y3Z4A",
"type": "user.invite",
"time": "2026-10-04T10:00:10.123456Z",
"data": {
"id": "aud_01JA2X5Q6R7S8T9V0W1X2Y3Z4A",
"time": "2026-10-04T10:00:10.123456+00:00",
"actorId": "usr_01J9Z8Q4M2N5P7R9T1V3X5Z7B9",
"action": "user.invite",
"summary": "Invited Sam Lee <sam@example.com>",
"targetType": "user",
"targetId": "usr_01JA2X5Q6R7S8T9V0W1X2Y3Z4B",
"target": "Sam Lee",
"ip": "203.0.113.7"
}
}
Sign-in events. The type is sign_in.success, sign_in.failure or sign_in.interrupted, and data is the sign-in event: id, time, userId (null when the attempt was not tied to an account), email, appId (null for sign-ins to Halo itself), result, method, ip, location, device, risk (none, low, medium or high) and, for failures, reason.
{
"id": "evt_01JA2X5Q6R7S8T9V0W1X2Y3Z4C",
"type": "sign_in.failure",
"time": "2026-10-04T10:02:41.512345Z",
"data": {
"id": "evt_01JA2X5Q6R7S8T9V0W1X2Y3Z4C",
"time": "2026-10-04T10:02:41.512345+00:00",
"userId": "usr_01J9Z8Q4M2N5P7R9T1V3X5Z7B9",
"email": "sam@example.com",
"appId": "app_01J9Z8Q4M2N5P7R9T1V3X5Z7C1",
"result": "failure",
"method": "passkey",
"ip": "203.0.113.7",
"location": "Amsterdam, Netherlands",
"device": "Chrome 130 · macOS",
"risk": "high",
"reason": "An administrator blocked this device."
}
}
The test event you send from an endpoint's page has the type webhook.test, and its data holds a message, the endpointId and sentBy, the email address of the administrator who sent it.
Event types
An endpoint subscribes to single event types, to families, or to everything:
- A type such as
user.suspendmatches only that event. - A family such as
user.*matches every type that starts withuser., including types Halo adds to the family in later versions. *matches every event, including types added later.
Choose single types when a receiver does one thing, such as suspending the person in another system; choose a family when it should see everything that happens in an area. GET /api/v1/webhooks/event-types returns each family with its types and these descriptions, and the console's event picker searches the same list.
The families are access_package.*, access_request.*, access_review.*, api_key.*, api_resource.*, application.*, branding.*, device.*, domain.*, group.*, identity_provider.*, lifecycle.*, lifecycle_rule.*, method.*, network_zone.*, organization.*, policy.*, provisioning.*, risk_event.*, role.*, saml_certificate.*, scim.*, service_account.*, session.*, settings.*, sign_in.*, signing_key.*, ssh.*, user.*, webhook.*. Their types are:
| Type | Sent when |
|---|---|
access_package.create |
An access package was created |
access_package.delete |
An access package was deleted |
access_package.update |
An access package was changed |
access_request.approve |
An access request was approved |
access_request.cancel |
A person cancelled their access request |
access_request.create |
A person requested an access package |
access_request.deny |
An access request was denied |
access_request.expire |
Granted access expired and its group memberships were removed |
access_request.revoke |
Granted access was revoked before it expired |
access_review.complete |
An access review was completed |
access_review.create |
An access review was started |
access_review.decide |
A reviewer kept a member or marked them for removal |
access_review.overdue |
An access review passed its due date with decisions missing |
api_key.create |
An API key was created for a service account |
api_key.revoke |
An API key was revoked |
api_resource.create |
An API was added |
api_resource.delete |
An API was deleted with its grants |
api_resource.grant |
The scopes an application has on an API changed |
api_resource.update |
An API's settings were changed |
application.create |
An application was registered |
application.delete |
An application was deleted with its credentials |
application.disable |
Sign-in to an application was turned off |
application.enable |
Sign-in to an application was turned on |
application.groups.update |
The groups assigned to an application changed |
application.logo.remove |
An application's logo was removed |
application.logo.update |
A new logo was uploaded for an application |
application.saml.update |
An application's SAML settings were changed |
application.secret.revoke |
An application's client secret or certificate was revoked |
application.secret.rotate |
A new client secret was created for an application |
application.update |
An application's settings were changed |
branding.logo.remove |
The sign-in logo was removed |
branding.logo.update |
A new sign-in logo was uploaded |
device.trust |
A device was marked trusted, blocked or unknown |
domain.add |
A domain was added for verification |
domain.remove |
A domain was removed |
domain.verify |
A domain was verified with a DNS TXT record |
group.create |
A group was created |
group.delete |
A group was deleted |
group.member.add |
A person was added to a group |
group.member.remove |
A person was removed from a group |
group.update |
A group's settings were changed |
identity_provider.create |
An identity provider was added |
identity_provider.delete |
An identity provider was deleted and its accounts unlinked |
identity_provider.disable |
Sign-in with an identity provider was turned off |
identity_provider.enable |
Sign-in with an identity provider was turned on |
identity_provider.update |
An identity provider's settings were changed |
lifecycle.run |
A lifecycle rule ran for a person |
lifecycle_rule.create |
A lifecycle rule was created |
lifecycle_rule.delete |
A lifecycle rule was deleted |
lifecycle_rule.update |
A lifecycle rule was changed |
method.update |
A sign-in method was turned on or off for the organization |
network_zone.create |
A network zone was added |
network_zone.delete |
A network zone was deleted |
network_zone.update |
A network zone was changed |
organization.export |
The organization was exported as JSON |
policy.create |
An access policy was created |
policy.delete |
An access policy was deleted |
policy.reorder |
The order of access policies changed |
policy.update |
An access policy was changed |
provisioning.configure |
Outbound SCIM provisioning was set up or changed for an application |
provisioning.sync |
People were pushed to an application over SCIM on demand |
risk_event.dismiss |
A risk event was dismissed |
risk_event.resolve |
A risk event was resolved |
role.update |
A person's administrator roles changed |
saml_certificate.delete |
A previous SAML signing certificate was removed |
saml_certificate.rotate |
A new SAML signing certificate was created |
scim.group.create |
A group was created through SCIM |
scim.group.delete |
A group was deleted through SCIM |
scim.group.update |
A group was changed through SCIM |
scim.user.create |
A person was provisioned through SCIM |
scim.user.deprovision |
A person was deprovisioned through SCIM |
scim.user.restore |
A person was restored through SCIM |
scim.user.suspend |
A person was suspended through SCIM |
scim.user.update |
A person's profile was changed through SCIM |
service_account.create |
A service account was created |
service_account.disable |
A service account was disabled |
service_account.enable |
A service account was enabled |
service_account.roles.update |
A service account's roles changed |
service_account.update |
A service account's settings were changed |
session.revoke |
An administrator ended a person's sessions |
settings.update |
Organization settings were changed |
sign_in.failure |
A sign-in failed or was blocked |
sign_in.interrupted |
A device sign-in was denied on the confirmation page |
sign_in.success |
A person signed in |
signing_key.rotate |
The OpenID Connect signing key was rotated |
ssh.certificate.issue |
An SSH certificate was issued |
ssh.lifetime |
The SSH certificate lifetime was changed |
ssh.mapping.create |
A group was mapped to SSH principals |
ssh.mapping.delete |
A group's SSH principals were removed |
ssh.mapping.update |
A group's SSH principals were changed |
user.authentication.reset |
A person's sign-in methods were reset |
user.avatar.remove |
A person's profile picture was removed |
user.avatar.update |
A person's profile picture was changed |
user.create |
An account was created on first sign-in through an identity provider |
user.enroll |
A person set up a passkey or security key from a setup link |
user.identity.link |
A person linked an account from an identity provider |
user.identity.unlink |
A person unlinked an account from an identity provider |
user.invite |
A person was invited |
user.method.add |
A person added a sign-in method or generated new recovery codes |
user.method.delete |
An administrator removed one of a person's sign-in methods |
user.method.remove |
A person removed one of their sign-in methods |
user.password.set |
An administrator set a temporary password for a person |
user.restore |
A suspended person's access was restored |
user.suspend |
A person was suspended |
user.update |
A person's profile was changed |
webhook.create |
A webhook endpoint was added |
webhook.delete |
A webhook endpoint was deleted |
webhook.update |
A webhook endpoint was changed, paused or resumed |
Add an endpoint
- In the console, open Webhooks and choose Add endpoint.
- Enter the URL. It must use https; plain http works only for
localhost, names under.localhostand loopback addresses while you test. - Choose the events: All events, which includes types added in later Halo versions, or Only the events I choose. In the list, tick a whole family such as
user.*, or expand it and tick single types such asuser.suspend. The search field finds a type by its name or description. Through the API,eventstakes between 1 and 50 entries, each a type, a family or*. - Save, and copy the Signing secret. It starts with
whsec_and Halo shows it only now. - Send a test event from the endpoint's page. Halo sends a
webhook.testevent right away, whatever the endpoint subscribes to, and shows the result.
An endpoint receives only events that happen after it was created. Pausing an endpoint stops deliveries: events that happen while it is paused are never sent, and deliveries that were already waiting resume when you turn it back on. Deleting an endpoint deletes its delivery log.
The secret cannot be changed. To replace it, add a new endpoint, move your receiver to the new secret, and delete the old endpoint.
Delivery
Halo looks for new events every 10 seconds and sends events that are at least 5 seconds old. Each delivery is an HTTP POST with:
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
Halo-Webhooks |
Halo-Signature |
t=<unix time>,v1=<hex HMAC-SHA256> |
- Any
2xxanswer within 10 seconds counts as delivered. Halo does not follow redirects, so a3xxanswer is a failure. - After a failure, Halo retries after 30 seconds, then waits twice as long before each further attempt: 1, 2, 4, 8, 16 and 32 minutes. After 8 attempts, about an hour after the first, the delivery is marked failed.
- Each event is queued once per endpoint. A retry sends the same body, with the same
id, and a new signature. - A retried delivery can arrive after newer events. Use
timeto order events andidto ignore ones you already processed.
The endpoint's page in the console lists its 50 most recent deliveries with their status, number of attempts, the HTTP status your endpoint answered, the error and the exact body sent.
Verify the signature
The Halo-Signature header has two parts:
t, the Unix time in seconds when Halo sent this attempt;v1, the hex-encoded HMAC-SHA256 oft, a dot, and the raw request body, keyed with the whole signing secret, includingwhsec_.
To verify a request:
- Read the raw body before parsing it. Re-encoding the JSON changes the bytes and breaks the signature.
- Split the header on
,and each part on=. - Reject the request when
tis more than 5 minutes away from your clock. - Compute the HMAC over
t + "." + bodyand compare it withv1in constant time. - Answer
2xxquickly, and do slow work afterwards.
A complete receiver in Go:
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"log"
"net/http"
"os"
"strconv"
"strings"
"time"
)
type event struct {
ID string `json:"id"`
Type string `json:"type"`
Time time.Time `json:"time"`
Data json.RawMessage `json:"data"`
}
func verify(secret []byte, header string, body []byte) bool {
var t, sig string
for _, part := range strings.Split(header, ",") {
key, value, _ := strings.Cut(part, "=")
switch key {
case "t":
t = value
case "v1":
sig = value
}
}
unix, err := strconv.ParseInt(t, 10, 64)
if err != nil || time.Since(time.Unix(unix, 0)).Abs() > 5*time.Minute {
return false
}
mac := hmac.New(sha256.New, secret)
mac.Write([]byte(t + "."))
mac.Write(body)
want := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(want), []byte(sig))
}
func main() {
secret := []byte(os.Getenv("HALO_WEBHOOK_SECRET"))
http.HandleFunc("POST /halo", func(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
if err != nil || !verify(secret, r.Header.Get("Halo-Signature"), body) {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
var e event
if err := json.Unmarshal(body, &e); err != nil {
http.Error(w, "invalid body", http.StatusBadRequest)
return
}
log.Printf("%s %s %s", e.Time.Format(time.RFC3339), e.Type, e.ID)
w.WriteHeader(http.StatusNoContent)
})
log.Fatal(http.ListenAndServe(":9100", nil))
}
Run it with the secret from step 4 of Add an endpoint:
HALO_WEBHOOK_SECRET=whsec_… go run .
Halo stores the secret encrypted with HALO_SECRET_KEY. If that key changes, Halo can no longer sign deliveries for existing endpoints; add new endpoints.
API
Endpoints are at /api/v1/webhooks, with /api/v1/webhooks/{id}/test to send a test event; see the API.