Events

Guardhouse sends webhook events as JSON envelopes. Event types and payloads are part of the Guardhouse server webhook contract, not a single SDK.

Validate the signature first, then deserialize and dispatch the event body.

Envelope

{
  "EventType": 1,
  "Data": {
    "UserId": 123,
    "Email": "[email protected]",
    "FirstName": "John",
    "LastName": "Doe"
  },
  "Timestamp": 1777036800
}

Field	Type	Description
EventType	integer	Numeric webhook event type.
Data	object	Event-specific payload.
Timestamp	integer	Unix timestamp, in seconds, generated for the delivery.

Event Types

Value	Event	Payload	Description
1	UserCreated	User payload	Sent when a user is created.
2	UserUpdated	User payload	Sent when an existing user is updated.
3	UserActivated	User payload	Sent when an invited user accepts the invitation and becomes active.

Event Details

UserCreated

UserCreated represents the creation of a Guardhouse user record.

Use this event when your application needs to create or sync a matching local user record after the user is created in Guardhouse. The payload contains the created user's Guardhouse identifier and basic profile fields.

If the user is created with an invitation, this event only means that the invited user record was created. It does not mean the invitee has accepted the invitation or can already be treated as active. Use UserActivated for invitation acceptance.

UserUpdated

UserUpdated represents a change to an existing Guardhouse user's profile data.

Use this event when your application keeps a local copy of user profile fields and needs to update it after Guardhouse changes. The payload contains the user's current identifier, email, first name, and last name at the time the webhook is sent.

This event is used for user profile updates. For example, a direct System API user update can trigger UserUpdated, and a successful verified email-change flow also sends the UserUpdated webhook event.

UserActivated

UserActivated represents the moment an invited user accepts the invitation and becomes active.

Use this event when your application needs to react to invitation acceptance, such as marking a previously invited local employee as active, enabling access in a downstream system, or starting post-activation onboarding.

This event is separate from UserCreated. An invited user can be created first and activated later, so receivers should not treat UserCreated as invitation acceptance.

User Payload

UserCreated, UserUpdated, and UserActivated currently use the same payload shape. Use EventType to decide what the payload means in the user lifecycle.

{
  "UserId": 123,
  "Email": "[email protected]",
  "FirstName": "John",
  "LastName": "Doe"
}

Field	Type	Description
UserId	integer	Guardhouse user identifier.
Email	string	User email address.
FirstName	string	User first name.
LastName	string	User last name.

Receiver Example

using System.Text.Json;
using Guardhouse.SDK.Webhooks;

app.MapPost("/webhooks/guardhouse", async (HttpRequest request, IConfiguration configuration) =>
{
    var secret = configuration["Guardhouse:Webhooks:Secret"];
    if (string.IsNullOrWhiteSpace(secret))
    {
        return Results.StatusCode(StatusCodes.Status500InternalServerError);
    }

    var isValid = await GuardhouseWebhookSignatureValidator.IsValidAsync(request, secret);
    if (!isValid)
    {
        return Results.BadRequest("Signature verification failed.");
    }

    var envelope = await request.ReadFromJsonAsync<JsonElement>();

    // Inspect EventType and deserialize Data to the matching event payload.
    return Results.Ok();
});

SDK Notes

SDKs may expose helper APIs for triggering webhook workflows or validating signatures, but the event list above is the webhook delivery contract.

Do not process the webhook body before validating X-Hub-Signature.