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
1	UserCreated	User payload
2	UserUpdated	User payload

User Payload

UserCreated and UserUpdated currently use the same payload shape.

{
  "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.