Webhooks

Webhooks are the mechanism in which out-of-band processes can communicate with an implemented service.

Message

For all webhooks, The TruValidate Multifactor Authentication Platform performs a HTTP POST request to a URL designated by the Customer. All Platform events trigger webhooks to the same URL. The particular event needed for processing when receiving the webhook HTTP request is discernible by its data elements.

Verification

The incoming request will be signed and encrypted in the same manner as an outgoing request from the API. See Cryptography for more information in that regard. All implementations should verify the request utilizing the JWT provided in the Authorization header of webhook requests.

The public key utilized to encrypt the webhook data is the same key utilized to initiate the process that triggered the webhook. For example, if the webhook is for an authorization response then the public key used to verify signature of the authorization request will be the public key used to encrypt the authorization response webhook.

Example request:

POST /launchkey/webhook HTTP/1.1
Host: service.customer.com
Content-Type: application/jose
Content-Length: 112
Authorization: IOV-JWT eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF

eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkEyNTZ.Ppd6dIAkGwcfIelfqOrj3rkw.71lYoW6jBJymhM-QLBQAWA.t-4rRH6GsoXt0.1DGC4k

Hint

To allow for processing of webhooks with key rotation, an implementation must allow processing webhooks from keys that may have expired between the time of the request initiating the process and the triggering of the webhook.

Mutual TLS (optional)

If you want to secure incoming webhook requests from TruValidate Multifactor Authentication on your network, we provide mutual TLS.

All requests with webhook urls specified to use HTTPS will validate the server certificate. In addition, webhooks will sign their requests with our own certificate. These can be verified on the Server’s end using the specified Subject Domain Name.

For Production webhooks the following SDN will be provided:

CN=webhooks.launchkey.com,O=iovation, Inc.,L=Portland,ST=Oregon,C=US

And for CI:

CN=ci-webhooks.launchkey.com,O=iovation, Inc.,L=Portland,ST=Oregon,C=US

Note

In some web servers iovation, Inc. may appear as iovationx5C, Inc.

In addition the DigiCert High Assurance EV Root CA should be trusted with a verification depth of 2 due to the certs being signed by the DigiCert SHA2 High Assurance Server CA.

User Contributed

TransUnion links to user contributed code as a resource to its community. TransUnion does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to TransUnion immediately and we will investigate the claim. Submit any issue to TransUnion support at https://transunion.com/support. ×