Skip to content
Halo

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.

JSON
{
  "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.

JSON
{
  "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.suspend matches only that event.
  • A family such as user.* matches every type that starts with user., 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

  1. In the console, open Webhooks and choose Add endpoint.
  2. Enter the URL. It must use https; plain http works only for localhost, names under .localhost and loopback addresses while you test.
  3. 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 as user.suspend. The search field finds a type by its name or description. Through the API, events takes between 1 and 50 entries, each a type, a family or *.
  4. Save, and copy the Signing secret. It starts with whsec_ and Halo shows it only now.
  5. Send a test event from the endpoint's page. Halo sends a webhook.test event 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 2xx answer within 10 seconds counts as delivered. Halo does not follow redirects, so a 3xx answer 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 time to order events and id to 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 of t, a dot, and the raw request body, keyed with the whole signing secret, including whsec_.

To verify a request:

  1. Read the raw body before parsing it. Re-encoding the JSON changes the bytes and breaks the signature.
  2. Split the header on , and each part on =.
  3. Reject the request when t is more than 5 minutes away from your clock.
  4. Compute the HMAC over t + "." + body and compare it with v1 in constant time.
  5. Answer 2xx quickly, and do slow work afterwards.

A complete receiver in Go:

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:

Bash
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.