How External Webhooks Work
When you create a webhook, you define a set of filters — channel, transaction stage, type, status, and source — that tell Neuroncx AI exactly which events should trigger an outbound call. Every time a transaction matches those filters, Neuroncx AI sends an HTTP POST request to the receiving endpoint. The payload includes an Identifier (a unique name you choose during setup) and the ExamID of the transaction, so your external system can correlate the event with the correct record. Authentication is handled through a Bearer Token that Neuroncx AI generates for you; the receiving endpoint must validate this token before processing the payload.Creating a Webhook
1
Open the Webhook Configuration Panel
From the main navigation, go to Settings → Channels → API and Hooks → External Webhooks. Click Create Webhook to open the configuration form.
2
Enter a Handle Name
Type a descriptive Handle Name for this webhook. This is the display name shown in the webhook list inside Neuroncx AI — use something that clearly identifies the purpose, such as
HIS Admission Sync or CRM Lead Update. The handle name is for your internal reference only and is not included in the outbound payload.3
Select a Channel
Choose the Channel that should trigger this webhook. Only transactions originating from or associated with the selected channel will be evaluated against your remaining filters. If you need to capture events across multiple channels, create a separate webhook for each one.
4
Set the Transaction Stage
Select the Transaction Stage at which the webhook should fire. The stage represents a specific point in the transaction lifecycle — for example, New, In Progress, or Closed. The webhook fires only when a transaction reaches or transitions through the stage you select here.
5
Provide an Identifier Name
Enter a value in the Identifier field. This name is included in every outbound webhook payload and is used by the receiving system to distinguish between different webhook sources or event types. Choose a short, machine-readable string such as
admission_confirmed or payment_received. You will share this name with the client alongside the bearer token.6
Select Transaction Type
Choose the Transaction Type to narrow which events fire this webhook. Transaction types map to the nature of the interaction recorded in Neuroncx AI — for example, a booking, an enquiry, or a follow-up. Selecting All causes the webhook to fire for every transaction type that meets the other criteria.
7
Select Transaction Status
Choose the Transaction Status filter. This lets you target only transactions in a specific state — such as Completed, Pending, or Cancelled — so your external system receives exactly the events it needs without additional client-side filtering.
8
Select Source
Pick the Source that should trigger this webhook. The source identifies the origin channel or entry point of the transaction, such as a WhatsApp flow, a web form, or an inbound call. Combined with the channel filter above, this gives you precise control over which traffic paths activate the webhook.
9
Generate the Bearer Token
Click Generate Bearer Token. Neuroncx AI creates a cryptographically secure token tied to this webhook. Copy and store this token immediately — you will not be able to retrieve it again after you leave this screen. If you lose it, you will need to regenerate a new token, which invalidates any integrations using the old one.
Treat the bearer token like a password. Store it in a secrets manager or secure vault on the receiving system. Never commit it to source control, include it in log output, or share it over unencrypted channels. If you suspect the token has been compromised, regenerate it from the webhook settings and update the receiving system immediately.
10
Save the Webhook
Review all your selections, then click Save. The webhook is now active. Neuroncx AI will begin dispatching POST requests to the configured endpoint as soon as a matching transaction event occurs.
Sharing Credentials with the Client
Once the webhook is created and saved, you need to provide the receiving system’s owner or integration team with three pieces of information so they can configure their endpoint to accept and validate incoming calls:Identifier Name
The unique name you entered in the Identifier field during setup. The receiving system uses this to identify which webhook source sent the payload.
Bearer Token
The token generated in the final setup step. The receiving endpoint must include this in its validation logic — typically by checking the
Authorization: Bearer <token> header on each incoming request.ExamID
The unique identifier for the exam or assessment associated with the transaction. You can find the ExamID in the URL of the relevant record inside the Neuroncx AI dashboard. Share this so the external system can match incoming events to the correct record in its own database.
Webhook Payload Overview
Every outbound webhook call from Neuroncx AI includes the following key fields in the JSON body:- identifier — the name you provided during setup, used to route the event on the receiving side
- examId — the unique ID of the transaction’s exam record, allowing cross-system correlation
- stage — the transaction lifecycle stage that triggered the webhook
- status — the transaction status at the time the event fired
- type — the transaction type
- source — the originating channel or entry point
- timestamp — the UTC time at which the event was recorded
Authorization header on every request carries Bearer <your-token>. The receiving endpoint should return an HTTP 200 OK to acknowledge receipt. Any non-2xx response will be logged as a delivery failure on the Neuroncx AI side.