A webhook is a common way to get updated of certain changes, such as when an authentication is completed. You register an https URL where the event data can be stored in JSON or XML formats. Webhooks are used differently for different API’s. For the SMS API we send a webhook every time SMS delivery status changes. Note that this may happen several times.
Webhook success Swedish BankID response example (json)
Normally the response body contains the same data as a normal collect result API call would return.
{
"identity": {
"CountryCode": "SE",
"FirstName": "LARS",
"LastName": "SVENSSON",
"FullName": "LARS SVENSSON",
"PersonalNumber": "191212121212",
"DateOfBirth": "1912-12-12",
"Age": 107,
"IdProviderName": "BankIDSE",
"IdentificationDate": "2018-10-22T08:26:41.8675683+02:00",
"IdProviderRequestId": "",
"IdProviderPersonId": "",
"CustomerPersonId": ""
},
"BankIDSE": {
"signature": "PD94….",
"ocspResponse": "MIIH…"
},
"method": "sbid-another",
"id": "61d300c2-cff8-4dc1-9abc-6d59f8876d32"
}Configuring your webhook settings
You need to provide ZignSec with http URL you would like to receive webhooks on. There are some tools that can help the development, for example, RequestBin, Pagekite and ngrok.
If you are unsure please contact ZignSec for help to set up your integration.
Receiving a webhook
Once you have registered a webhook we will send HTTP POST calls to the Specified URL each time an event occurs. POST data contains relevant information from the event that triggered the request.
To acknowledge that you have received data of an webhook, your endpoint should return a 2xx HTTP status code. If a webhook for any reason are not received correctly, ZignSec will try 3 times.
It is important that a webhook answered as quickly as possible. It is recommended to wait to process until after a response has been sent.
Verify a webhook created through the API
Webhooks created through the API can be verified by calculating a digital signature. X-ZignSec-Hmac-SHA256 header which is generated using the AppID secret you have from ZignSec. It also use the data sent in the request.
Please note that this feature is available for eid’s with the test.zignsec.com/v2/ and api.zignsec.com/v2/ endpoints we are currently working with adding verification for our other implementations. It is also possible to use IP whitelisting to confirm the origin of a webhook.
To verify that a Webhook comes from ZignSec calculate the HMAC digest according to the algorithm below, and compare with the X-ZignSec-Hmac-SHA256 header. If they match, you can be sure that the Webhook was sent from ZignSec and the data has not been compromised.
byte[] data = Encoding.UTF8.GetBytes(postedJSONString);
using (HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(yourPersonalAccessTokenString)))
{
callbackRequest.Headers.Add("X-ZignSec-Hmac-SHA256", System.Convert.ToBase64String(hmac.ComputeHash(data)));
}
