Webhook integration

Introduction

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:

  1. SSH into the OpenCRVS manager node and register a new system client
  2. Securely host the system client_id, client_secret and 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:

  1. Create an endpoint on a secure server that can process HTTPS requests.
  2. Authenticate and query OpenCRVS to find a list of available event webhooks.
  3. Authenticate and subscribe to the Webhook of choice and configure your endpoints.
  4. 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.

Verification Requests

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

GET https://www.your-clever-domain-name.com/webhooks?
opencrvs.mode=subscribe&
opencrvs.challenge=1158201444&
opencrvs.verifyToken=abcdefghijklmnopqrstuvwxyz
ParameterSample valueDescription
opencrvs.modesubscribeThis value will always be set to subscribe
opencrvs.challenge1158201444An int you must pass back to OpenCRVS
opencrvs.verifyTokenabcdefghijklmnopqrstuvwxyzYou will set this string when you complete the subscription process

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 opencrvs.challenge value.

Event Notifications

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:

POST / HTTPS/1.1
Content-Type: application/json
X-Hub-Signature: sha1={super-long-SHA1-signature}
{
"id": "531e9275-40e4-4ab5-a12c-6fa74d7b5b61",
"address": "https://www.your-clever-domain-name.com/webhooks",
"createdAt": "2019-12-12T10:53:43-08:00",
"createdBy": {
"client_id": "8636abe2-affb-4238-8bff-200ed3652d1e",
"type": "api",
"username": "sys.admin",
"name": "Euan Millar"
}
"target": {
"id": "bab755e0-7bbd-4d90-b155-352ffa283467",
"resourceType": "Composition"
},
"trigger": "BIRTH_REGISTERED"
}
ParameterSample valueDescription
id531e9275-40e4-4ab5-a12c-6fa74d7b5b61The unique id for this webhook. Helpful when debugging.
addresshttps://www.your-clever-domain-name.com/webhooksThe URL that is notified by this webhook
createdAt2019-12-12T10:53:43-08:00A timestamp identifying the time that the webhook was created
createdBy.client_id8636abe2-affb-4238-8bff-200ed3652d1eThe unique client_id for the client subscriber.
createdBy.typesystemValue is always system for a client subscriber.
createdBy.usernamesys.adminThe OpenCRVS username associated by the System Administrator responsible for creating the client subscriber in the subscription process.
createdBy.nameEuan MillarThe full name of the System Administrator responsible for creating the client subscriber in the subscription process.
target.idbab755e0-7bbd-4d90-b155-352ffa283467The unique id for the FHIR resource target that this webhook refers to.
target.resourceTypeCompositionThe FHIR resource type associated with the target of this webhook, e.g. Composition for a FHIR Composition.
triggerBIRTH_REGISTEREDA 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.

Validating Payloads

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 \u00e4\u00f6\u00e5.

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.

Subscription process

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 client_id and client_secret.

List available webhooks

This API returns webhooks that are owned by the authenticated client service

URL

GET https://webhooks.<your-open-crvs-host.com>/webhooks

Request headers

Content-Type: application/json
Authorization: Bearer <token>

Response payload

Example json

{
"entries": [
{
"id": "531e9275-40e4-4ab5-a12c-6fa74d7b5b61",
"address": "https://www.your-clever-domain-name.com/webhooks",
"createdAt": "2019-12-12T10:53:43-08:00",
"createdBy": {
"client_id": "8636abe2-affb-4238-8bff-200ed3652d1e",
"type": "api",
"username": "sys.admin",
"name": "Euan Millar"
}
"trigger": "BIRTH_REGISTERED"
}
]
}

Subscribe to a webhook

This API subscribes a client service to an OpenCRVS webhook using a supported OpenCRVS event type string as a trigger.

URL

POST https://webhooks.<your-open-crvs-host.com>/webhooks

Request headers

Content-Type: application/json
Authorization: Bearer <token>

Request payload

{
"address": "https://www.your-clever-domain-name.com/webhooks",
"trigger": "BIRTH_REGISTERED"
}
ParameterSample valueDescription
addresshttps://www.your-clever-domain-name.com/webhooksThe URL address that will be requested when the event occurs.
triggerBIRTH_REGISTEREDA supported OpenCRVS event type string that will trigger this webhook.

The supported events and associated trigger string:

Webhook eventtrigger
Birth registrationBIRTH_REGISTERED
Death registrationDEATH_REGISTERED
Birth certifiedBIRTH_CERTIFIED
Death certifiedDEATH_CERTIFIED
Birth correctedBIRTH_CORRECTED
Death correctedDEATH_CORRECTED

Response payload

Example json of created webhook object:

{
"id": "531e9275-40e4-4ab5-a12c-6fa74d7b5b61",
"address": "https://www.your-clever-domain-name.com/webhooks",
"createdAt": "2019-12-12T10:53:43-08:00",
"createdBy": {
"client_id": "8636abe2-affb-4238-8bff-200ed3652d1e",
"type": "api",
"username": "sys.admin",
"name": "Euan Millar"
}
"trigger": "BIRTH_REGISTERED"
}

Unsubscribe to a webhook

This API unsubscribes a client service to an OpenCRVS webhook using the webhook id.

URL

DELETE https://webhooks.<your-open-crvs-host.com>/webhooks/<your-webhook-id>

Request headers

Content-Type: application/json
Authorization: Bearer <token>

Response

Status code and an empty response will be returned when the webhook has been successfully deleted.

204

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.