DocumentaciónHelp

Enable the webhook and send events

Get the webhook URL and signing secret and configure your system to send its events to the platform.

On this page

The webhook is the address your system sends its events to. Each integration has its own, plus a Signing secret your system uses to sign each submission. That way the platform only accepts events that really come from your system.

Before you start

  • You need the Administrator role.

  • The integration must exist. If you created it with Receive events by webhook checked, the webhook is already active and you saw the secret when you saved it.

  • You need someone who can configure the external system to send signed requests.

Enable the webhook

  1. Go to Settings → Integrations.

  2. On the integration's card, the Webhook field says Disabled. Press Webhook.

  3. The Webhook enabled window opens. There is no prior confirmation: pressing the button generates the URL and the secret.

Copy the URL and the secret

The Webhook enabled window shows the notice Copy the secret now: it's shown only once.

  1. Next to Webhook URL, press Copy.

  2. Next to Signing secret, press Copy.

  3. Paste them into your system's configuration or store them in your secrets manager.

  4. Press I've copied it, close. In Have you copied the secret?, confirm with Yes, close. If you close the window another way, this confirmation is also requested.

The platform stores the secret encrypted and can't show it again. If you lose it, you'll have to Rotate or disable the webhook and configure the system again.

How your system must send events

The same window includes the instructions in How to send events and ready-to-copy examples in the curl and Node.js tabs (Copy example button). In short:

  1. Send a POST with a JSON body to the webhook URL.

  2. Add the X-Argunis-Timestamp header with the current time in Unix seconds.

  3. Add the X-Argunis-Signature: sha256=<signature> header, where the signature is the hex HMAC-SHA256, calculated with the secret, of timestamp + "." + body (the exact body you send).

  4. Invalid signatures, or ones more than 5 minutes off the server time, are rejected. You can send one event or a list of events (a JSON array).

Each event states its type (type: alerta, incidente, activo or vulnerabilidad, that is, alert, incident, asset or vulnerability) and its severity (severity: baja, media, alta or critica, that is, low, medium, high or critical), plus an identifier, a title, when it occurred and the affected asset:

{
  "type": "alerta",
  "id": "alert-1234",
  "title": "Múltiples intentos fallidos de RDP",
  "severity": "alta",
  "occurredAt": "2026-09-29T14:05:00Z",
  "asset": {
    "externalId": "agent-017",
    "name": "srv-files",
    "hostname": "srv-files.empresa.local",
    "ip": "10.0.4.30",
    "os": "Windows Server 2022"
  }
}

Always send the event's id in your system. If the same event arrives twice (because of a retry), the platform recognizes it by that identifier and doesn't duplicate it.

Make sure the sending system's clock is synchronized. With more than 5 minutes of difference, the platform rejects the submission even if the signature is correct.

What happens next

Each accepted event appears in the Received events tab and the card updates Last event. Depending on the type:

  • Alerts, incidents, vulnerabilities and other events come in with New status, so someone can review them. A type other than the four known ones is recorded as Other, and a severity other than the four known ones is ignored.

  • Assets always come in with Reviewed status. If the integration has Assets for the inventory checked, the asset is recorded as a discovered asset (or linked to the one you already have with the same host name or IP). Review new ones in the Discovered tab of Company → Assets to add them to the inventory. See Add or discard discovered assets.

  • If the event includes an asset that already exists in your inventory (by host name or IP), it is linked to it.

  • If the integration has Automatic incident, critical-severity alerts and incidents open an incident immediately.

If the integration is Paused, the webhook doesn't accept events.

If events don't arrive

Ask whoever configures the external system to check the response it gets when sending:

Response

What it means

202

The submission was accepted. If you don't see it, check the Received events filters.

401, "Firma inválida o vencida." (invalid or expired signature)

The secret is wrong, the signature wasn't calculated over the exact body sent, or the system's clock is more than 5 minutes off.

404

The URL doesn't exist: the webhook was rotated or disabled, or the integration is Paused.

429

Too many submissions from the same address (more than 120 per minute). Group several events in a list.

Related

Search SofIA Governance

Type at least 2 characters to search SofIA Governance.

↑↓ to navigate · Enter to open · Esc to close