Integrations Module
Machine-to-machine integration layer — outgoing webhooks with HMAC-SHA256 signing, API key management, event routing, and delivery audit.
The Integrations module owns all machine-to-machine integration concerns. Outgoing webhooks notify external systems when SCRIPE events occur. API keys allow external systems to call SCRIPE APIs without OAuth. The module is fully isolated — webhook configuration never bleeds into Identity or Entitlements.
Webhook System
WebhookSubscription (in Core.Domain) stores the endpoint URL, subscribed event types (JSON array), and HMAC-SHA256 signing secret. On every domain event, the WebhookDispatcher finds active subscriptions matching the event type and dispatches an HTTP POST with X-SCRIPE-Signature-256 header. Failures are logged in WebhookDeliveryLog and retried with exponential backoff. Secret rotation is supported — PreviousSecret remains valid for 24 hours after rotation.
API Key Management
API keys are tenant-scoped with comma-separated permission scopes. Key values are NEVER stored — only a bcrypt hash (KeyHash) is persisted after generation. The prefix (first 8 chars) allows key identification without exposing the secret. Keys can have an optional ExpiresAt and can be revoked instantly via RevokedAt.
Security
All webhook payloads are signed with HMAC-SHA256 using the subscription secret. Receivers MUST validate the X-SCRIPE-Signature-256 header before processing. API keys use bcrypt hashing (OWASP recommendation). Webhook URLs must be HTTPS in production. A circuit breaker disables subscriptions after 10 consecutive failures to prevent hammering unreachable endpoints.
Permissions
integrations.connections.view/create/update/delete | integrations.apikeys.view/create/revoke | integrations.webhooks.view/create/update/delete | integrations.events.view | integrations.export