Skip to main content
A webhook lets Neurapulse notify your own system when something happens in your workspace, instead of your system having to ask. You register a URL you control and choose which events it should receive; Neurapulse then sends an HTTPS POST request to that URL whenever one of those events occurs. The first available event is a test taker completing an assessment, with more event types to come.
Webhook payloads carry identifiers and status information only. They never include scores or percentiles, for any event type.

​
Managing Your Webhooks

Webhooks are managed per workspace, under Workspace Settings → Webhooks. Each workspace can register up to 5 URLs.
1

Add a webhook

Choose Add new webhook, select the events you want delivered, and enter your endpoint URL. The URL must use https:// and point to a publicly reachable address.
2

Save your signing secret

When the webhook is created, Neurapulse shows its signing secret (whsec_...) exactly once. Copy it and store it securely in your receiving system, because it cannot be viewed again. If it is lost, delete the webhook and add it again to get a new secret.
3

Test the URL

From the webhook’s actions menu (⋮), choose Test URL. Neurapulse sends a signed webhook.test request to your endpoint and shows the response inline, so you can confirm connectivity before real events flow.
From the same actions menu you can also edit which events a URL receives, enable or disable it, and delete it. Deleting a webhook removes all of its event subscriptions and stops deliveries immediately.

​
What a Delivery Looks Like

Every delivery is an HTTPS POST with a JSON body and three headers: An example test_result.completed payload:
  • projectId is the id of the project the test belongs to, as shown in the portal. Use it to route deliveries when several projects feed the same endpoint.
  • completionStatus is the test’s status, most commonly Completed or HighRisk. Treat it as an open set and don’t fail on unfamiliar values; a value of HighRisk is the signal that the result needs attention.
  • referenceId is your own identifier for the test taker, if one was supplied (see Reference IDs); otherwise null.
  • topPerformer is a derived categorical indicator, matching the topPerformer field the API returns for the same test taker. It is never a score or a ranking.
  • identityStatus is the ID verification outcome for the test taker’s most recent attempt: Verified, VerificationPending, NotVerified, VerificationOff, or Compromised. Verified covers both digital and manual verification. VerificationOff means verification was deliberately switched off for that test taker; an empty string means no verification status was recorded for the attempt at all, for example in a project that does not use ID verification or for a result from before the feature existed. Treat it as an open set. Compromised means the attempt was flagged during continuous screening and is not a passing result.
Your endpoint should respond with a 2xx status code promptly. Any other response, or no response within 10 seconds, counts as a failed delivery.

​
Verifying the Signature

Always verify deliveries before trusting them. Anyone who discovers your endpoint URL could send it fake requests. The signature proves a request came from Neurapulse and was not altered. Compute an HMAC-SHA256 of "{timestamp}.{raw request body}" using your signing secret, and compare it (hex-encoded, prefixed with sha256=) to the X-Neurapulse-Signature header:
Reject requests whose timestamp is more than a few minutes old. Because the timestamp is part of the signed material, this prevents captured requests from being replayed later.
Each URL has its own signing secret, and all events delivered to that URL are signed with the same one, so your receiver only needs one secret per endpoint.

​
Retries and Automatic Disabling

Deliveries are retried automatically, so a brief outage on your side does not lose events:
  • A failed delivery is retried with increasing delays: roughly 1 minute, 5 minutes, 30 minutes, 2 hours, then 12 hours.
  • After 5 consecutive failures, the delivery is abandoned and the webhook URL is automatically disabled to stop sending into a dead endpoint.
  • A disabled webhook stays visible in Workspace Settings with a Disabled status. Once your endpoint is healthy again, re-enable it from the actions menu and deliveries resume for new events.
Deliveries can occasionally arrive more than once for the same event. Use testResultId to deduplicate if your system is sensitive to repeats.

​
Requirements and Limits

  • URLs must use https:// and resolve to a public address. Internal or private-network addresses are rejected.
  • Redirects are not followed; the registered URL must answer directly.
  • Up to 5 webhook URLs per workspace; the same URL can subscribe to multiple event types as they become available.