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.

Your webhookFusionAuthYour serviceYour webhookFusionAuthYour servicePOST /api/user with eventInfo.data200 OKuser.create event with event.info.data

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 Authorization header, 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.

  1. Add eventInfo.data to 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' }
        }
      })
    });
  2. In your webhook, check the Authorization header, then read event.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 include event.info.data.
  • The Identity Provider Link API ignores eventInfo in the request.
  • Logins through the hosted login pages don't take eventInfo from your application. FusionAuth fills in event.info from 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.