Skip to content

Webhooks and privacy

The package supplies opt-in request-authentication middleware only. It does not register webhook routes, validate provider event schemas, process events, persist or deduplicate deliveries, or send acknowledgments. Your Laravel application owns these responsibilities.

Mono shared-secret header

Configure MONO_WEBHOOK_SECRET and attach VerifyMonoWebhookSecret to your application-owned route:

use Alphabalex\IdentityMadeEasy\Http\Middleware\VerifyMonoWebhookSecret;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/mono', [MonoWebhookController::class, 'handle'])
    ->middleware(VerifyMonoWebhookSecret::class);

The middleware compares the incoming mono-webhook-secret header to the configured value using a constant-time comparison. Missing configuration, missing header, or a mismatch returns HTTP 401. This is a shared-secret header check; it is not a signature of the request body.

IdenVault timestamped HMAC

Configure IDENVAULT_WEBHOOK_SECRET separately from IDENVAULT_API_KEY, then attach VerifyIdenVaultWebhookSignature:

use Alphabalex\IdentityMadeEasy\Http\Middleware\VerifyIdenVaultWebhookSignature;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/idenvault', [IdenVaultWebhookController::class, 'handle'])
    ->middleware(VerifyIdenVaultWebhookSignature::class);

The expected X-IdenVault-Signature header is t=<unix timestamp>,v1=<hex>. The signature is HMAC-SHA256 of {timestamp}.{raw request body}, keyed by the webhook secret. The default allowed timestamp difference is 300 seconds. Invalid configuration, malformed/stale timestamps, or invalid signatures return HTTP 401. Do not parse and re-encode the body before signature verification.

Process deliveries safely

After authentication, your controller should validate the event envelope before use, enqueue durable processing, and return a success response only when the event has been accepted. Make processing idempotent because providers may deliver an event more than once. Where the event provides a stable ID, persist it with a uniqueness constraint to prevent duplicate processing. Return a non-2xx response when validation or enqueueing fails so provider retry behavior can take effect; follow the provider's acknowledgment deadline and retry documentation.

Do not log full webhook bodies or identity data. Redact secrets and identifiers from error reporting.

Identity-data responsibilities

Identity and verification calls can process sensitive personal information. Before requesting live verification:

  • Establish consent or another lawful basis and provide required notices.
  • Send truthful provider request-reason fields when the API requires them.
  • Collect only data needed for the purpose, and minimize retention.
  • Restrict access and encrypt retained sensitive data according to your application controls.
  • Avoid logging API credentials, request/response bodies, full identifiers, or SDK session tokens.
  • Handle provider results and error responses in accordance with your jurisdiction and contractual obligations.

The package transports provider requests and returns provider results; it does not collect consent, determine your legal basis, or implement application data-retention policy.