Webhooks

Webhooks let Neostra call your systems when something happens: a subject request starts or completes, a breach incident moves through its workflow, an assessment reaches a milestone, or a visitor submits consent. You define where to send the call once as an API configuration, then attach it to rules in each module with a Call API action. Every delivery is logged, retried, and can be replayed from the UI.

How it works

1. You create an API configuration: the target URL, retry settings, and how Neostra authenticates to your endpoint.
2. You add a Call API action to a rule in a module (DSAR workflow, breach workflow, assessment template, or consent collection point) and pick that configuration. The rule defines when the call fires and what JSON body to send.
3. When the rule matches, Neostra creates a run, sends an HTTP POST with a JSON body to your URL, retries on failure, and records the result in Webhook Delivery Logs.

One configuration can be shared by rules in several modules. Each run is attributed to the module that fired it.

Create an API configuration

Go to Admin > Integrations > API Configuration and click Add.

Authentication types

Secrets are encrypted at rest and are write only. After you save, the UI never shows the key, token, or password again; the form shows only that a secret is set. When editing, leave the secret field blank to keep the existing value, or type a new value to replace it. Changing the auth type requires a fresh secret. Selecting None removes any stored secrets.

Auth headers are added on every attempt and always take precedence over a rule level custom header of the same name.

Attach a Call API action to a rule

Each module exposes a Call API action inside its rules. In every case you pick an API configuration, optionally add custom headers, and write the JSON request body. The body editor supports static values and {{variable}} placeholders, and lists the variables available in that module.

Writing the request body

The body you write is a JSON object whose values can be literals, placeholders, or strings that mix both.

• A value that is exactly one placeholder, such as "{{requests}}", keeps the variable's native type. Lists become JSON arrays and timestamps become ISO 8601 strings.
• A value with surrounding text, such as "Request {{requestId}} is {{status}}", is sent as a string with the placeholders replaced.
• Unknown placeholders are left untouched, so check spelling against the variable list in the editor.
• Neostra adds a top level timestamp field (ISO 8601, when the run was created) unless your body already defines one.

Example body written in the DSAR rule editor:

{
  "event": "dsar.completed",
  "requestId": "{{requestId}}",
  "status": "{{status}}",
  "requestTypes": "{{requests}}",
  "subject": {
    "email": "{{requestorEmail}}",
    "country": "{{requestorCountry}}"
  }
}

Custom headers

Rule level headers are for correlation and tracing, for example a X-Correlation-Source: neostra header your gateway routes on. Configure authentication on the API configuration instead of in rule headers. In Consent Management rules, placeholders in header values are replaced with the submission's values. In other modules, header values are sent as entered.

What your endpoint receives

Neostra sends a single POST per attempt.

POST /your/webhook/path HTTP/1.1
Host: your-host.example.com
Content-Type: application/json
X-Neo-Idempotency-Key: 3f6d1a2b-8c4e-4b1f-9a7d-2e5c6f8a9b01
Authorization: Bearer <your configured token>
X-Correlation-Source: neostra

{
  "event": "dsar.completed",
  "requestId": "66c0a1f2e4b0a1b2c3d4e5f6",
  "status": "FULFILLED",
  "requestTypes": ["access"],
  "subject": {
    "email": "data.subject@example.com",
    "country": "IN"
  },
  "timestamp": "2026-06-18T10:02:44.512Z"
}

The body is exactly what you defined in the rule plus timestamp. There is no fixed envelope, so design a shape that suits your receiver and include an event field if one configuration serves several rules.

Idempotency key

Every run carries an X-Neo-Idempotency-Key header with a UUID. The same key is sent on every retry attempt of that run and on every manual replay of it. Store the keys you have processed and ignore repeats so that retries and replays never double process an event.

Retries and failure handling

• A delivery counts as successful when your endpoint returns a 2xx response.
• Any other outcome (non 2xx status, connection error, or timeout) counts as a failed attempt. Neostra waits Retry Interval seconds and tries again, up to Max Attempts in total (default 3, with a 30 second timeout per attempt).
• When every attempt fails the run is marked FAILED and kept with its full payload and headers. Failed runs are not retried automatically after that point; you replay them manually from the delivery log.

Run statuses you will see in the log: CREATED, IN_PROGRESS, COMPLETED, FAILED.

Delivery logs and replay

Go to Admin > Integrations > Webhook Delivery Logs. The table lists every run with its run id, the source record (for example SubjectRequest: <request id> or ConsentReceipt: <receipt id>), API configuration name, module, status, HTTP response code, triggered and completed times, and duration.

• Filter by module (Consent Management, Data Subject Requests, Assessments, Breach Management) and by status.
• Search by Run ID or by Entity ID (the request, incident, assessment, or consent receipt id) to find every delivery for one record.
• Expand a row to see the exact request payload that was sent and the response body your endpoint returned.
• Replay appears on FAILED runs. It creates a new run linked to the original, using the stored payload, custom headers, and the same idempotency key. Each failed run can be replayed up to 3 times. When a replay succeeds the original is marked Resolved and the Replay button disappears.

Replaying uses the API configuration as it is now, so fix the target URL or credentials first, then replay.

Verifying calls on your side

Neostra does not sign webhook bodies. Use the mechanisms that exist:

• Shared secret: configure API Key, Bearer Token, or Basic Auth on the API configuration and reject calls that do not present it. Rotate it by editing the configuration.
• HTTPS only: expose the endpoint over TLS so the secret and payload are protected in transit.
• Idempotency: deduplicate on X-Neo-Idempotency-Key.
• Cross check: for DSAR events, you can confirm the record with the Integration API status endpoint before acting on it.