Webhook clients
Business functionality and API endpoints available to a "Webhook" client.
Last updated
Business functionality and API endpoints available to a "Webhook" client.
Last updated
OpenCRVS publishes the following civil registration events as webhooks that clients can subscribe to. This is particularly useful for e-Gov systems if you wish to initiate business functionality for a citizen at the moment a Birth or Death is officially registered.
Birth registration
Death registration
Included in these webhooks is a FHIR Resource type and unique ID to the OpenCRVS resource associated and customisable demographics, attachments and links to biometric data for the registration in a SHA signed and encrypted payload.
Subscribing to an OpenCRVS webhook requires you to develop a service that exposes the standardised and required webhook endpoints associated with the pattern.
Any service that subscribes to an OpenCRVS webhook must:
Expose endpoints on a secure server that can process HTTPS requests and respond to a webhook following the pattern.
Authenticate and query OpenCRVS to find a list of available event webhooks.
Authenticate and subscribe to the webhook of choice.
Respond to the webhook event as you wish internally, and request further details from OpenCRVS via a if you need to.
Your mediator must be able to process two types of HTTPS requests:
Verification Requests
Webhook Events.
Since both requests use HTTPs your server must have a valid TLS or SSL certificate correctly configured and installed.
The following sections explain what will be in each type of request to these endpoints and how to respond to them.
Anytime you try to subscribe to a webhook, OpenCRVS will send a GET request to this endpoint URL to confirm that your mediator is prepared to receive webhook events.
Sample:
mode
subscribe
This value will always be set to subscribe
challenge
1158201444
A random cryptographic string that you must pass back to OpenCRVS
topic
BIRTH_REGISTERED
A supported OpenCRVS event type string that will trigger this webhook
Note: The supported events and associated topic strings are explained later in this document when studying the subscription process.
Whenever your endpoint receives a verification request, it must:
Verify that the topic
value matches the event you're trying to subscribe to. Respond with the following object:
Whenever there's a a new event created, we will send your endpoint a POST request with a JSON payload. When you create or edit a webhook client, you select the data you wish to be contained in the payload using the checkboxes.
For example, if you subscribed to the birth registration event, we would send you a POST request to the same URL as the Verification request URL that would look something like this depending on what content you configured in the screen above:
payload.id
531e9275-40e4-4ab5-a12c-6fa74d7b5b61
The unique id
for this webhook. Helpful when debugging.
payload.timestamp
2019-12-12T10:53:43-08:00
A timestamp identifying the time that the webhook was created
payload.event.hub.topic
BIRTH_REGISTERED
A supported OpenCRVS event type string that triggered this webhook.
payload.event.context
[{ ... }]
url
https://www.your-clever-domain-name.com/webhooks
The URL that is notified by this webhook
hmac
sha256=d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f
The request signature that is created using your sha_secret
explained below.
We encrypt the payload using your client's sha_secret
in an SHA256 signature hash and include the hash in the request's hmac
property, preceded with sha256=
.
You must confirm that the data is genuinely received from OpenCRVS and not from a malicious man-in-the-middle by using the sha_secret in this way
To validate the payload in a similar way to our method:
Generate a SHA256 signature using the context
array contents at position [0] as the rawBody
. signingSecret
is your OpenCRVS sha_secret
, available to you as an environment variable and generated via the register step. requestSigningVersion
is "sha256"
Compare your signature to the hmac
prop. If the signatures match, the payload is genuine.
Please note that we generate the signature using an escaped unicode version of the payload, with lowercase hex digits. If you just calculate against the decoded bytes, you will end up with a different signature. For example, the string äöå
should be escaped to \u00e4\u00f6\u00e5
.
Your endpoint should respond to all events with 200 OK HTTPS
.
Frequency: Be sure to adjust your servers to handle each Webhook individually and at any time.
Firstly, ensure that you have correctly configured your subscriber endpoint above to respond to Verification Requests and Webhook Events.
With the token you can now perform the following actions:
This API returns all clients that are subscribed to receive webhook notifications.
URL
Example json
This API subscribes a client service to an OpenCRVS webhook using a supported OpenCRVS event type string as a trigger.
Parameters contained within the hub
object:
callback
https://www.your-clever-domain-name.com/webhooks
The URL address that will be requested when the event occurs.
mode
subscribe
Always set to subscribe
for this action.
topic
BIRTH_REGISTERED
A supported OpenCRVS event type string that will trigger this webhook.
secret
d04aec67-1ef4-467a-a5a8-fa5c89ad71ce
The supported events and associated topic string:
Birth registration
BIRTH_REGISTERED
Death registration
DEATH_REGISTERED
The subscribe process will test the authenticity of the sha_secret
and additionally make a test GET request to the Verification Request
Provided all is successfully completeed, your webhook will be subscribed and you will receive a 202 status code and empty response.
This API unsubscribes a client service to an OpenCRVS webhook using the webhook id.
204 status code and an empty response will be returned when the webhook has been successfully deleted.
The property context
contains the FHIR bundles. Refer to our section to learn more about the FHIR specification.
The bundle associated with the target of this webhook.
This shows how we create the signature to help you understand how you might create a similar hash and compare them.
Unacknowledged responses are retried according to the capabilities of our library used .
To subscribe, your subscription service must request an using your client_id
and client_secret
.
Your OpenCRVS sha_secret
, available to you via the mediator step.