Webhooks and Event Subscriptions

Overview#

Webhooks push platform events to external systems in real time: when an event occurs in Argus, each subscribed endpoint receives an authenticated HTTP POST carrying the full event payload within seconds, with no polling required.

A SOC team wants their SIEM to receive every authentication failure and account lockout event the moment it happens. An IT automation system needs to provision accounts in downstream systems as soon as a user joins an organisation, not on the next scheduled sync. A compliance team needs an immutable log of all platform events flowing to cold storage for regulatory audit purposes. Webhooks handle all three through the same subscription model.

The delivery architecture includes automatic retry with exponential backoff, cryptographic signature verification on every payload, and idempotency keys so receiving systems can safely deduplicate without missing events. Subscriptions that target named providers such as Jira, ServiceNow, PagerDuty, Slack, and Microsoft Teams are provider-aware: the platform offers only the event types each provider actually accepts, validates destination addresses before anything leaves the platform, and surfaces subscription problems as clear warnings rather than silent non-delivery.

Open Standards#

• HMAC-SHA256 (RFC 2104 / FIPS 198-1): Every outbound webhook delivery is authenticated with an HMAC-SHA256 signature carried as a hex-encoded digest in a dedicated signature header, allowing receiving systems to verify payload authenticity and integrity.
• Standard Webhooks (HMAC-SHA256): Webhook deliveries follow the Standard Webhooks signing pattern, pairing HMAC-SHA256 signatures with per-delivery identifiers and timestamps so receiving systems can verify each message using a widely understood scheme.
• JSON (RFC 8259 / ECMA-404): All event payloads are serialised as JSON and transported with the application/json media type; the envelope structure, including event type, timestamp, delivery ID, and data body, is a plain JSON object.
• RFC 3339 / ISO 8601 Timestamps: Event envelope timestamps are produced as UTC ISO 8601 strings, for example 2026-06-05T10:00:00+00:00, ensuring unambiguous, timezone-aware time representation that any consuming system can parse.
• UUID (RFC 4122): Delivery identifiers and subscription identifiers are version-4 random UUIDs, used as idempotency keys so receiving endpoints can safely deduplicate retried deliveries.
• HTTPS / TLS (RFC 8446): All webhook deliveries and the subscription management API operate exclusively over HTTPS; outbound requests are subject to server-side request forgery protection that enforces publicly routable HTTPS target URLs, pins the validated destination address to block redirects into internal networks, and enforces TLS certificate verification on every delivery.
• OAuth 2.0 (RFC 6749): The webhook management API (create, list, update, delete subscriptions) is protected by the platform's OAuth 2.0 Bearer token authentication layer, and OAuth client and token events are a first-class supported event category.

Key Features#

• Cryptographic Signature Verification: Every webhook delivery includes an HMAC-SHA256 signature header for payload authenticity verification, preventing unauthorised or tampered payloads from being accepted
• Broad Event Coverage: Subscribe to events across user lifecycle, MFA, security, SSO, organisation, session, and OAuth categories
• Automatic Retry Logic: Failed deliveries are retried up to 3 times with exponential backoff, ensuring reliable event delivery even during temporary endpoint unavailability
• Delivery History and Debugging: View delivery attempt details including status codes, response bodies, and error messages for each webhook to diagnose integration issues
• Selective Event Subscription: Subscribe to only the event types needed, minimising network traffic and focusing on events relevant to the integration
• Provider-Aware Event Selection: Subscriptions targeting Jira, ServiceNow, PagerDuty, Slack, or Microsoft Teams offer only the event types each provider accepts, and event types a provider can never receive are rejected at configuration time; paging services follow a lifecycle-only contract (trigger, acknowledge, resolve) so activity chatter never pages the on-call team
• Visible Subscription Health: Subscriptions holding event types a provider will never deliver are flagged with a clear explanation localised in English, Spanish, and French; creation and update errors surface as real messages rather than empty states, and provider status counts refresh immediately after subscriptions change without a page reload
• Safe Subscription Reconfiguration: Changing a provider subscription preserves existing ticket links and retires superseded links atomically, so external references never break mid-change
• Destination Allowlist Validation: Customer-configured destination URLs are validated against provider-shaped allowlists at configuration time and again at send time
• Hardened Outbound Delivery: Every delivery passes a server-side request forgery guard that validates and pins the destination address and enforces TLS certificate verification, and webhook shared secrets are accepted only through request headers, never through URL query strings where they could be logged
• Webhook Management API: Create, list, update, and delete webhooks through a self-service API with full lifecycle management
• Tenant Isolation: Users can only manage and receive events for their own webhooks, with complete data separation between organisations
• Standard Payload Format: All events use a consistent JSON payload structure with event type, timestamp, event-specific data, and organisation context
• Idempotency Support: Each delivery includes a unique delivery identifier usable as an idempotency key to prevent duplicate processing on the receiving side
• Delivery Statistics: Track delivery success rates and failure counts per webhook for integration health monitoring

Supported Event Categories#

• User Events: Account creation, login, logout, password changes, email changes, and profile updates
• MFA Events: MFA enablement, disablement, passkey registration, and challenge failures
• Security Events: Breach attempt detection, account lockouts, suspicious login detection, and password breach notifications
• SSO Events: SSO authentication completions, provider linking, and provider unlinking
• Organisation Events: User additions, removals, and role changes within organisations
• Session Events: Session creation, termination, and concurrent session limit events
• OAuth Events: Client registration, token issuance, and token revocation

Use Cases#

• SIEM platforms subscribe to security events to receive real-time breach detection alerts, aggregate authentication failures, and trigger automated incident response workflows
• IT automation systems subscribe to user lifecycle events to provision and deprovision accounts in downstream systems when users are added to or removed from organisations
• Compliance teams stream all platform events to immutable log storage for regulatory audit trails, monitoring privileged user activities and MFA enrolment patterns
• DevOps teams monitor OAuth client and token events to track third-party application authentication activity and detect anomalous token usage patterns
• Custom integrations use webhook events to synchronise platform changes with CRM records, ticketing systems, or notification channels in real time
• Administrators wire incident lifecycle paging to PagerDuty while routing activity events to Slack or Microsoft Teams channels, with provider-aware event pickers preventing configurations that would never deliver

Integration#

The Webhooks system connects with the platform's authentication layer for secure webhook management, the event processing pipeline for reliable event capture and delivery, and supports integration with any external system capable of receiving HTTPS POST requests and verifying HMAC-SHA256 cryptographic signatures. Named provider integrations for Jira, ServiceNow, PagerDuty, Slack, and Microsoft Teams build on the same unified subscription model, so operators configure every provider the same way while each is delivered against its own vendor API, and all outbound connections route through the platform's server-side request guard with TLS verification.

Last Reviewed: 2026-07-16 Last Updated: 2026-07-16