Pass Context From API Requests to Webhooks
On this page
You can attach your own data to a FusionAuth API request, such as a trace Id or the name of the service that made the call. FusionAuth copies the data into the events the request triggers. Your webhook can then tie each event back to the API call that caused the event, without a second API call.
The data travels in the eventInfo.data field of the request body. FusionAuth delivers the data, without changes, as event.info.data in the webhook payload.
FusionAuth copies eventInfo.data from an API request into the event that the request triggers.
Prerequisites#
- A FusionAuth API key with permission to call the API you use.
- A webhook that listens for the events the request triggers, with those events enabled on the Tenant. For more information, see Write a Webhook.
- A shared secret in the webhook's
Authorizationheader, so your webhook can reject events that don't come from FusionAuth. For more information, see Secure Webhooks.
Send and Read the Context#
The following example creates a user and reads the trace Id from the user.create event. The code comes from the webhooks example repository, which includes a Docker Compose file and a Kickstart that configure the webhook.
-
Add
eventInfo.datato the API request body. The object can hold any JSON:Create a user with context const response = await fetch(`${fusionAuthURL}/api/user`, { method: 'POST', headers: { 'Authorization': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ user: { email: `user-${traceId}@example.com`, password: 'password' }, eventInfo: { data: { traceId, requestedBy: 'billing-service' } } }) }); -
In your webhook, check the
Authorizationheader, then readevent.info.data:Read the context in the webhook function isFromFusionAuth(req) { const received = Buffer.from(req.header('Authorization') || ''); const expected = Buffer.from(webhookSecret); return received.length === expected.length && crypto.timingSafeEqual(received, expected); } app.post('/webhook', (req, res) => { // reject requests without the shared secret, so no one else can send fake events if (!isFromFusionAuth(req)) { res.sendStatus(401); return; } const event = req.body.event; // eventInfo.data from the API request arrives as event.info.data const context = event.info?.data || {}; console.log(`received ${event.type} with traceId ${context.traceId} from ${context.requestedBy}`); res.sendStatus(200); });
To confirm the result, send the request and check your webhook's output. The webhook logs the same traceId that the request sent. You can also find the event, with event.info.data, in the Webhook Event Log.
Which Requests Accept Context#
Most calls to the User, Registration, Login, Logout, JWT, and Two Factor APIs carry eventInfo into events. A call carries the field when the call's request body reference lists eventInfo. For example, the Tenant and Application APIs list eventInfo for updates, but not for creates.
The following requests don't carry eventInfo.data into events:
- The Group and Entity APIs don't accept
eventInfo. Events from those APIs never includeevent.info.data. - The Identity Provider Link API ignores
eventInfoin the request. - Logins through the hosted login pages don't take
eventInfofrom your application. FusionAuth fills inevent.infofrom the browser request instead.
Other Event Info Fields#
eventInfo also accepts details about the end user, such as ipAddress, userAgent, and deviceName. When your server calls FusionAuth on behalf of an end user, set those values from the end user's request. Otherwise, events and login records show the address of your server. FusionAuth always sets event.info.location from the IP address, and ignores a location in the request. For the full list of fields, see the Create a User request body.
Related
Learn about FusionAuth events.
API documentation for the FusionAuth Create a Webhook API.
API documentation for the FusionAuth Delete a Webhook API.
Learn about the APIs for creating, retrieving, updating and deleting Webhooks.