Receive messages on a webhook

A webhook gives a sending system its own private HTTPS address. The system posts each message to it with a key, and gets an HTTP status back straight away.

Before you begin

Have the following ready:

1. A sending system that can make an HTTPS POST request with a header.
2. The feed the messages should go into.
3. The admin role in the workspace.

1. Add the webhook

1. Open Sources and select New source.
2. Select Webhook.
3. Enter a Name, for example GP referrals webhook.
4. Under Send messages into, choose the feed.
5. Under Sender proves who it is with, choose:
   • API key (X-API-Key or Bearer): the sender puts the key in an X-API-Key header, or in Authorization: Bearer <key>.
   • Basic auth (user name + key): the sender uses HTTP Basic sign-in, with the User name you set and the key as the password.
6. Select Add source.

New webhook source

2. Copy the key

A banner shows the webhook's key, starting rhk_.

The key is shown once, straight after the webhook is added

1. Select Copy key.
2. Store it in the sending system's configuration, or pass it to whoever manages that system through your usual secure channel.

The key is shown only once

NEEV keeps only a fingerprint of the key, so it cannot be shown again. If it is lost, an admin selects New key. The old key stops working at once.

3. Send a test message

1. Select Send a test message. The dialog fills in a sample admission, and the key if it is still on screen; otherwise paste it.
2. Select Send.

The dialog posts to the webhook's address with the webhook's key, exactly as the sending system will, and shows the answer: "HTTP 200 · AA Accepted. The message is in Messages." Select Open in Messages to see it.

A test message accepted with HTTP 200 and AA

4. Switch it on and connect the sender

1. Switch the webhook on in the Sources list.
2. Give the sending system the Address from the panel and the key.

What the sending system sends

curl -X POST 'https://<your NEEV address>/api/integration/_inbound/<webhook token>/' \
  -H 'X-API-Key: rhk_…' \
  -H 'Content-Type: application/hl7-v2' \
  --data-binary @admission.hl7

Use Content-Type: application/hl7-v2 for HL7 v2 and application/json for JSON. The body is the message itself, one message per request.

What the sending system gets back

Status	Meaning	What the sender should do
200	Accepted. The body includes "ack_code": "AA" and a correlation_id to quote if anyone asks about the message.	Nothing.
401	The key or password is not right for this source. The attempt is recorded as a security event.	Check the key.
403	The address only accepts HTTPS.	Use the https:// address.
422	The message reached the pipeline and was refused, for example because it is not HL7. The reason is in the answer, and the message is in Messages.	Fix the message; do not resend unchanged.
503	The webhook, or the feed it sends into, is switched off. The answer includes Retry-After. Nothing is stored.	Hold the message and send it again later.