Event Forwarding
Event forwarding sends your organization's SVID issuance events, as they happen, to an HTTPS endpoint you choose. The endpoint can be a security vendor that ingests identity signals, a SIEM, a webhook collector, or a service you run yourself.
You decide where events go and which ones to send. Defakto builds each event, queues it, signs it, delivers it, and retries failed deliveries.
| Aspect | Behavior |
|---|---|
| Event types | svid-issued (one event per JWT-SVID or X.509-SVID issued) |
| Format | One Security Event Token (SET) per delivery, adhering to the OpenID Shared Signals Framework |
| Authentication | A bearer JWT signed by a key unique to your organization, verifiable against a public JWKS. There is no shared secret to store or rotate. |
| Delivery guarantee | At least once, with no ordering guarantee |
| Configured with | The Defakto Console, spirlctl, or Terraform |
Each destination is an event subscription. An organization can have up to 10.
Event forwarding requires spirlctl 0.37.0 or later.
How It Works
Each subscription has its own delivery queue. A destination that is slow or down delays only its own events.
Before You Start
Confirm the following with whoever operates the destination. If the destination is a vendor product, the vendor's integration documentation should cover each item. If your vendor needs more detail, or you are building your own receiver, contact Defakto support.
| Requirement | Detail |
|---|---|
| An HTTPS URL | The full URL that accepts events: scheme, host, and path. Plain HTTP is rejected. |
| Public reachability | The Defakto Control Plane must reach the URL over the public internet, and the URL's certificate must be publicly trusted. |
| JWT bearer verification | The destination verifies a bearer JWT against a public JWKS. Static API keys and shared secrets are not supported. See Details for Your Vendor. |
| Fast response | The destination responds 202 as soon as each event is stored and processes it afterward, within 300 ms. A destination that does work before responding risks failed deliveries. |
| Duplicate handling | Delivery is at least once, so the same event can arrive more than once. The destination handles duplicates, typically by deduplicating on the SET's jti. |
Also decide which trust domains to cover, and confirm with your security team which workload attributes may leave your environment. See Controlling What Is Sent.
Creating a Subscription
You can manage subscriptions in the Defakto Console under Organization → Event subscriptions, with spirlctl, or with Terraform. The examples below use spirlctl.
Creating, updating, and deleting subscriptions requires the Administrator role. Viewing them requires Auditor or above. See Roles.
spirlctl event-subscription create \
--destination https://receiver.example.com/events \
--event-type svid-issued
Before saving, Defakto sends the destination a verification event. If the destination does not accept it, the request fails and nothing is saved.
Creating, updating, or deleting a subscription provisions delivery infrastructure in the background. The request waits for provisioning to finish, which can take a few minutes.
Example output:
Event subscription created:
ID: esub-0123456789
Destination: https://receiver.example.com/events
Enabled: true
Event types:
svid-issued
Authentication: SPIFFE JWT-SVID
Created: 2026-09-22T16:04:05Z
Updated: 2026-09-22T16:04:05Z
Flags
| Flag | Required | Description |
|---|---|---|
--destination | Yes | The HTTPS URL events are delivered to. Must be unique within your organization, and must not contain credentials. |
--event-type | Yes | An event type to deliver. Repeat for more than one. svid-issued is the first supported event type. |
--trust-domain-id | No | Deliver only events from this trust domain. Repeat for more than one. Defaults to every trust domain, including ones created later. Find IDs with spirlctl trust-domain list. |
--disabled | No | Create the subscription without turning delivery on. A disabled subscription is not sent a verification event. |
To limit a subscription to multiple trust domains, repeat the --trust-domain-id flag for each trust domain:
spirlctl event-subscription create \
--destination https://receiver.example.com/events \
--event-type svid-issued \
--trust-domain-id td-m36ckrte4e \
--trust-domain-id td-888butgzdc
Managing Subscriptions
Viewing subscriptions
spirlctl event-subscription get
This lists every subscription in your organization, including its ID, destination, event types, trust domain filter, and whether delivery is on.
Updating a subscription
update changes only the fields you pass. Every other field stays as it is.
# Turn delivery off without deleting the subscription
spirlctl event-subscription update --subscription-id esub-0123456789 --disabled
# Turn it back on
spirlctl event-subscription update --subscription-id esub-0123456789 --enabled
# Replace the trust domain filter
spirlctl event-subscription update --subscription-id esub-0123456789 --trust-domain-id td-m36ckrte4e
# Remove the trust domain filter, delivering from every trust domain
spirlctl event-subscription update --subscription-id esub-0123456789 --trust-domain-id ""
--event-type and --trust-domain-id replace the current list rather than adding to it.
Defakto sends a verification event before saving any update that leaves the subscription enabled. If the destination does not accept it, the update is not saved.
The destination URL cannot be changed, because the authentication audience is derived from it. To move to a new URL, create a subscription for the new URL, confirm events arrive, then delete the old one.
Deleting a subscription
spirlctl event-subscription delete --subscription-id esub-0123456789
When changes take effect
Changes reach the delivery pipeline within about a minute. Until then, events continue to route under the previous configuration.
| Action | What happens |
|---|---|
| Create or enable | Delivery starts for events issued after the change takes effect. Earlier events are not backfilled. |
| Disable or delete | Events stop being queued once the change takes effect. Events already queued may still be delivered for a few minutes. |
| Re-enable | Delivery resumes with new events only. Events issued while the subscription was disabled are never delivered. |
Verification Event
When a subscription is created or enabled, Defakto sends the destination a single SET carrying the SSF verification event type, https://schemas.openid.net/secevent/ssf/event-type/verification. The request is authenticated the same way as every other delivery.
The subscription is saved only if the destination responds 202 within 300 ms. See Before You Start. A failure here means the destination is unreachable, too slow, rejecting the bearer token, or the URL is wrong.
What Is Sent
Each event identifies the workload by its SPIFFE ID, and includes details of the issued SVID and the workload attributes collected at issuance. No credential is sent in a usable form, and no private key material is sent.
The SET JSON Schema is the full reference for the event format.
Details for your vendor
Every delivery carries a bearer JWT signed with a key unique to your organization. Give whoever operates the destination these values so it can verify deliveries:
| URL | |
|---|---|
| Issuer | https://fed.spirl.org/<org_id> |
| JWKS | https://fed.spirl.org/<org_id>/jwks |
<org_id> is your organization ID, in the form t-0123456789. Find it in the Defakto Console under Organization → Profile, in the Organization ID field.
The token's aud is the subscription's destination URL.
Controlling What Is Sent
Subscriptions filter by event type and trust domain. They cannot filter which workload attributes an event includes.
To keep an attribute out of forwarded events, use attribute redaction. Redacted attributes are removed before the issuance event is created, so they never appear in a forwarded event. Redaction is not specific to a subscription: An attribute is either visible both in Defakto and to every destination, or redacted from all of them.
The attributes in an event depend on how the workload was attested and on your redaction configuration, so different events can carry different attributes.
What to Expect
Event forwarding is a live feed, not a complete record. Failed deliveries are retried a few times over several seconds, and events that cannot be delivered within five minutes are dropped. This first release does not backfill or replay missed events. If a destination misses events, for example because it was down or a subscription was disabled, Defakto cannot fill the gap.
Events can also arrive out of order.