Receivers

Overview

This guide sets up Britive to send its own security events to a receiver, such as a SIEM. When a mapped Britive event occurs, such as an administrator disabling a user, Britive sends a CAEP or RISC event to the receiver.

What you’ll accomplish:

Add the receiver in Britive and map a Britive event to a CAEP or RISC event
Trigger the Britive event and confirm the receiver got it

Before You Begin

A Britive user who can manage Shared Signals, for example through TenantAdminRole or SecurityAdminRole. See Permissions.
A receiver endpoint that accepts POST requests with Content-Type: application/secevent+jwt
For the API steps, a Britive API token for that user

How It Works

    sequenceDiagram
    participant A as Britive admin or user
    participant B as Britive
    participant R as Receiver
    A->>B: Action, for example disable a user
    B->>B: Look up receivers mapped to the Britive event
    B->>R: POST signed SET (application/secevent+jwt)
    R-->>B: 2xx response
    Note over B: Result recorded in Shared Signals > Events

Britive sends each event as a Security Event Token (SET) in an HTTP POST:

Part	Value
Method	`POST` to the Receiver URL
`Content-Type`	`application/secevent+jwt`
Other headers	The receiver’s custom headers, if any
Body	The signed SET, as a compact JWT

The SET contains these claims:

Claim	Value
`iss`	`https://<your-tenant-domain>`
`aud`	The receiver’s Receiver URL
`iat`, `jti`	When the SET was issued, and a unique ID
`sub_id`	`{"format": "email", "email": "<user's email>"}`
`events`	One CAEP or RISC event, with `event_timestamp` and `subject`

The SET is signed with RS256, and its header has typ: secevent+jwt and a kid. To verify the signature, use the key with that kid from your tenant’s key endpoint:

https://<your-tenant-domain>/api/auth/sso/oauth2/keys

Receivers that use OpenID Connect discovery can find this endpoint from the SET’s iss. It is the jwks_uri in https://<your-tenant-domain>/.well-known/openid-configuration.

Britive sends an event only when the event’s target, such as the user, has an email address.

Limitations

No SSF discovery. Britive does not publish SSF discovery metadata (/.well-known/ssf-configuration). Receivers that find keys only through SSF discovery, such as caep.dev, cannot verify the signature.
Push delivery only. The receiver cannot create or manage a stream with Britive. An administrator adds the receiver in Britive.
Events carry only event_timestamp and subject. Some CAEP events require more claims. For example, Credential Change requires credential_type and change_type, and Assurance Level Change requires namespace and current_level. A receiver that enforces these requirements rejects those events. The suggested events in Britive Events need no other claims.

To verify that an event came from Britive, check the SET’s signature with the key endpoint in How It Works. If the receiver also requires HTTP authentication, or cannot use the key endpoint, add a custom header, such as Authorization: Bearer <secret>, that holds a shared secret the receiver checks. Britive sends the header with every event. It is not part of the signed SET. Custom headers can be set only through the API. See the API tab in Add the Receiver in Britive.

Britive Events

These Britive events can be sent to a receiver. Any Britive event can be mapped to any CAEP or RISC event. An event is suggested only where it matches the Britive event and needs no claims beyond those Britive sends. See Limitations.

Britive event	`britiveEventType`	Suggested event
User Disabled	`user.disable`	Account Disabled (RISC)
User Enabled	`user.enable`	Account Enabled (RISC)
User Deleted	`user.delete`	Account Purged (RISC)
Service Identity Disabled	`service.identity.disable`	Account Disabled (RISC)
Service Identity Enabled	`service.identity.enable`	Account Enabled (RISC)
Service Identity Deleted	`service.identity.delete`	Account Purged (RISC)
Password Reset by Admin	`admin.reset.password`	None
Password Changed by User	`user.self.update.password`	None
MFA Enrolled	`mfa.registration.completed`	None
MFA Removed	`mfa.registration.deleted`	None
MFA Removed by Admin	`mfa.registration.admin.deleted`	None
Force Checkin All	`admin.access.checkin`	None
API Token Created	`api.token.create`	None
API Token Revoked	`api.token.revoke`	None

Force Checkin All is sent once for each checkout that is checked in for the user by someone else: an administrator, a Shared Signals action, or Britive, for example when the user’s access to the profile is revoked. It is not sent when the user checks in or a checkout expires.

A RISC account event refers to the account its subject identifies. In events from Britive, that is the user or service identity, not a cloud account.

Delivery

Britive waits up to 10 seconds for the receiver to respond. Any 2xx response counts as delivered.
A delivery that fails or times out is retried, up to 3 attempts in total. If delivery to any receiver fails, Britive sends the event again to every receiver mapped to it. A resent event has a new jti.
Every delivery attempt is recorded in Events, with direction Transmitted.

Add the Receiver in Britive

Using the Britive Console

Open the Receivers tab

Click Admin → Security → Shared Signals → Receivers.

Add the receiver

Click Add, enter a name and the Receiver URL, then click Save.

Name:          SIEM
Receiver URL:  https://siem.example.com/ssf/events

Open the receiver’s mappings

Click Manage on the receiver, then click the Mappings tab.

Map a Britive event

Select the Britive event under Action and the CAEP or RISC event under Event. Click the row’s Add icon, then click Save.

Action:  User Disabled
Event:   risc-account-disabled

Using the API

List the Britive events

The catalog lists the Britive events that can be sent. Use a type value from it in the mapping.

curl -s "https://$BRITIVE_TENANT/api/ssf/admin/catalog" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" | jq '.britiveEventTypes'

Add the receiver

Header values are stored encrypted and returned masked as ******. The response includes the new receiver’s receiverId.

RECEIVER_ID=$(curl -s -X POST "https://$BRITIVE_TENANT/api/ssf/admin/receivers" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receiverUrl": "https://siem.example.com/ssf/events",
    "displayName": "SIEM",
    "headers": {"Authorization": "Bearer <receiver-secret>"}
  }' | jq -r '.receiverId')

Map a Britive event to a CAEP or RISC event

This call replaces all of the receiver’s mappings. Include every mapping you want to keep.

curl -s -X PUT "https://$BRITIVE_TENANT/api/ssf/admin/receivers/$RECEIVER_ID/mappings" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      {
        "britiveEventType": "user.disable",
        "eventUri": "https://schemas.openid.net/secevent/risc/event-type/account-disabled"
      }
    ]
  }'

Set the header on an existing receiver

For a receiver added in the Britive Console, or to change the secret. To find the receiver’s ID, list the receivers.

curl -s "https://$BRITIVE_TENANT/api/ssf/admin/receivers" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" | jq '.items[] | {receiverId, displayName, receiverUrl}'

This call replaces all of the receiver’s headers.

curl -s -X PATCH "https://$BRITIVE_TENANT/api/ssf/admin/receivers/$RECEIVER_ID" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"headers": {"Authorization": "Bearer <receiver-secret>"}}'

Verify

Trigger the Britive event

Perform the mapped action on a test user. For the example mapping, disable the user in the Britive Console, or through the API:

curl -s -X POST "https://$BRITIVE_TENANT/api/users/test.user@example.com/disabled-statuses" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN"

Check the receiver

Confirm the receiver got a POST with a SET whose events claim contains the mapped event URI, and that the SET’s signature verifies with the key endpoint in How It Works.

Check the result in Britive

Open Admin → Security → Shared Signals → Events, filter by Transmitted, and expand the newest entry. It shows the Receiver URL, the status, and the outcome. See Events.

Troubleshoot

Symptom	Cause	Fix
The receiver gets nothing, and nothing appears in Events	The Britive event is not mapped for this receiver, the event’s target has no email address, or the receiver is disabled	Check the receiver’s mappings and the target’s email address. To enable the receiver, send `PATCH /api/ssf/admin/receivers/{receiverId}` with `{"enabled": true}`
The event failed, and its outcome starts with `HTTP 401` or `HTTP 403`	The receiver rejected the request	Add the header the receiver expects through the API
The event failed with another HTTP status, or the outcome shows a timeout	The receiver returned an error or did not respond within 10 seconds	Check the receiver’s logs and that the Receiver URL is reachable from the internet
The receiver rejects the SET signature	The receiver looks for keys only through SSF discovery, which Britive does not publish	Configure the receiver with the key endpoint or the OpenID Connect discovery URL in How It Works
The receiver rejects the event as missing required claims	The mapped event requires claims that Britive does not send	Map a suggested event from Britive Events
The receiver got the same event more than once	A delivery was retried. A resent event has a new `jti`	Treat repeats of the same event for the same subject as one event

To see an event’s outcome, expand it in Events, or read the outcome field from the API.

Next Steps

Events: review sent events and their results
Transmitters: receive events from an identity provider

Last updated on October 28, 2026

Transmitters Events