In order to make OpenCRVS as useful and open as possible to other systems, OpenCRVS publishes the following civil registration events as Webhooks that systems can subscribe to.
- Birth registration
- Death registration
- Birth certified
- Death certified
- Birth corrected
- Death corrected
Included in the webhook will be a FHIR Resource type and uniqe ID to the resource associated. Once a subscriber receives the event, they can query OpenCRVS for demographics, attachments and links to biometric data for the registration in a dedicated and secure API.
Subscribing to an OpenCRVS Webhook requires your system administrator to:
- SSH into the OpenCRVS manager node and register a new system client
- Securely host the system
sha_secret, returned in the registration process, as environment variables or Docker Secrets that your subscriber service has secure access to.
Subscribing to an OpenCRVS Webhook requires your subscribing system client to:
- Create an endpoint on a secure server that can process HTTPS requests.
- Authenticate and query OpenCRVS to find a list of available event webhooks.
- Authenticate and subscribe to the Webhook of choice and configure your endpoints.
- Develop a mediator to respond to the Webhook to request sensitive demographic or biometric details required for your system. Refer to the MOSIP mediator.
These steps are explained in detail below.
Creating a subscriber endpoint
Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed.
The sections below explain what will be in each type of request and how to respond to them.
Anytime you subscribe to a Webhook, OpenCRVS will send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:
Sample Verification Request
|This value will always be set to |
|You will set this |
Validating Verification Requests
Whenever your endpoint receives a verification request, it must:
Verify that the
opencrvs.verifyToken value matches the string you set in the verifyToken field when you configure the Webhooks.
Respond with the
When you configure your Webhooks product, you will subscribe to specific events. Whenever there's a a new event created, we will send your endpoint a POST request with a JSON payload describing the event FHIR Compostion ID.
For example, if you subscribed to the birth registration event, we would send you a POST request that would look something like this:
|The unique |
|The URL that is notified by this webhook|
|A timestamp identifying the time that the webhook was created|
|The unique |
|Value is always |
|The OpenCRVS |
|The full name of the System Administrator responsible for creating the client subscriber in the subscription process.|
|The unique |
|The FHIR resource type associated with the target of this webhook, e.g. |
|A supported OpenCRVS event type string that triggered this webhook.|
By using the target.id and target.resourceType, a subsequent integration can be used to retrieve the details of the event as FHIR resources. Follow the National ID integration mediator provided for an example use case.
We sign all Event Notification payloads with a SHA1 signature and include the signature in the request's
X-Hub-Signature header, preceded with
sha1=. You don't have to validate the payload, but you should.
To validate the payload:
Generate a SHA1 signature using the payload and your OpenCRVS
sha_secret, available to you via the register step.
Compare your signature to the signature in the
X-Hub-Signature header (everything after
sha1=). 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
Responding to Event Notifications
Your endpoint should respond to all Event Notifications with
200 OK HTTPS.
Frequency Be sure to adjust your servers to handle each Webhook individually and at any time.
Unacknowledged responses will not be retried, but will be logged on the manager node.
Firstly, ensure that you have correctly configured your subscriber endpoint above to respond to Verification Requests.
Next, your subscription service must request an Authorization Bearer token using your
List available webhooks
This API returns webhooks that are owned by the authenticated client service
Subscribe to a webhook
This API subscribes a client service to an OpenCRVS webhook using a supported OpenCRVS event type string as a trigger.
|The URL address that will be requested when the event occurs.|
|A supported OpenCRVS event type string that will trigger this webhook.|
The supported events and associated trigger string:
Example json of created webhook object:
Unsubscribe to a webhook
This API unsubscribes a client service to an OpenCRVS webhook using the webhook id.
Status code and an empty response will be returned when the webhook has been successfully deleted.
Mediator documentation describing how to request FHIR resources
OpenCRVS is working in partnership with MOSIP - the Modular Open Source Identity Platform in order to define the following approach and standards to integrate civil registration and National ID as an example Mediator.
OpenCRVS will publish birth events to MOSIP and subscribe to a similar webhook on the MOSIP platform to retrieve a generated National ID to assign to the newly registered individual.