Webhooks¶
Webhooks allow the GRC-ITSM platform to send real-time HTTP notifications to external systems when specific events occur. This is the primary mechanism for connecting the platform to the n8n automation pipeline that powers many of the GRC-ITSM workflows.
Navigation
Configuration > Integrations > Webhooks on the GRC-ITSM website navigation.
How Webhooks Work¶
When an event occurs in the platform (a ticket is created, a status changes, an approval is completed, etc.), the webhook sends an HTTP POST request to a configured URL with a JSON payload containing the event details. The receiving system - typically an n8n workflow - processes the payload and executes whatever automation logic is defined.
This event-driven model means automations run in near real-time as things happen in the platform, rather than relying on polling or scheduled checks.
Webhook Configuration¶
Each webhook is configured with:
| Setting | Purpose |
|---|---|
| URL | The endpoint that receives the webhook payload (e.g., an n8n webhook trigger URL) |
| Event Type | Which platform event triggers the webhook |
| HTTP Method | Typically POST for outbound webhooks |
| Headers | Custom HTTP headers, commonly used for authentication tokens or API keys |
| Payload | The data included in the request body. The platform sends event-specific JSON containing the relevant ticket, user, or entity data |
| Authentication | Credentials or tokens used to secure the webhook endpoint |
| Active/Inactive | Toggle the webhook on or off without deleting the configuration |
Event Types¶
Webhooks can be triggered by a wide range of platform events, including:
- Ticket events - creation, status changes, assignment changes, priority changes, SLA breaches
- Approval events - approval requested, approved, rejected
- Action events - notes added, attachments uploaded
- Entity events - user created, asset updated, configuration changes
The specific events available depend on the platform configuration and the entity types involved.
Role in the GRC-ITSM Pipeline¶
Webhooks are the connective layer between the GRC-ITSM platform and the n8n automation engine. Many of the platform's compliance-driven workflows rely on webhooks to trigger automated processes:
Common Webhook-Triggered Workflows¶
| Trigger Event | Automated Workflow |
|---|---|
| Alert ticket created | n8n processes the alert, enriches it with context from security tools, and routes it for triage |
| Change request approved | n8n notifies the implementation team and updates the change management calendar |
| User access request submitted | n8n validates the request details and routes it through the approval pipeline |
| Issue ticket SLA approaching breach | n8n sends escalation notifications to the assigned agent and team lead |
| Vulnerability deviation approved | n8n updates the related issue tickets and ConMon tracking records |
| Scheduled ticket generated | n8n triggers automated evidence collection for data request fulfillment |
These automations reduce manual effort and ensure that compliance-critical processes execute consistently and on time.
Security Considerations¶
Webhooks transmit platform data to external endpoints, so they require appropriate security controls:
Authentication¶
Always secure webhook endpoints with authentication. Common approaches:
- Header-based tokens - include a shared secret or API key in a custom HTTP header that the receiving endpoint validates
- HMAC signatures - the platform signs the payload with a shared secret, and the receiver verifies the signature to confirm the request is authentic
- URL-based tokens - include a unique token in the webhook URL itself (less secure than header-based methods)
Network Controls¶
- Webhook endpoints should only be accessible from the GRC-ITSM platform's outbound IP addresses where possible
- Use HTTPS for all webhook URLs to encrypt data in transit
- For self-hosted deployments within a FedRAMP boundary, ensure the webhook destination is also within the boundary or is a documented external connection per CA-3 and SC-7
Data Minimization¶
Configure webhook payloads to include only the data needed by the receiving workflow. Avoid sending sensitive fields (credentials, CUI) unless the receiving endpoint has appropriate protections and the data flow is documented in the SSP.
Troubleshooting¶
Common issues when working with webhooks:
| Issue | Likely Cause | Resolution |
|---|---|---|
| Webhook not firing | Webhook is set to inactive, or the event type doesn't match the expected trigger | Verify the webhook is active and the event type matches the action being performed |
| Endpoint returns 401/403 | Authentication headers are missing or incorrect | Check that the authentication token or API key in the webhook headers matches what the endpoint expects |
| Endpoint returns 500 | The receiving workflow encountered an error processing the payload | Check the n8n execution log for the failed workflow run |
| Payload missing expected data | The webhook is configured with a limited payload, or the event type sends different data than expected | Review the payload configuration and test with a sample event to inspect the actual JSON sent |
| Duplicate webhook fires | Multiple webhooks configured for the same event, or the event triggers more than once during processing | Review webhook configuration for duplicates and check whether the platform event fires at multiple stages |
Testing Webhooks
When setting up a new webhook, use a test endpoint (such as an n8n webhook trigger in test mode) to inspect the payload structure before building the automation logic. This lets you see exactly what data the platform sends for each event type.