In this guide, we will look at how to receive and consume webhooks to integrate your app with ZignSec. With webhooks, your app can know when something happens in ZignSec, such as a user completing an identity verification or a screened individual suddenly showing up in a sanction list. ## Receiving webhooks To receive webhooks, you need to have a URL in your app that ZignSec can call. The webhook URL must be sent in the webhook parameter of requests made to the ZignSec API. Whenever this is provided, you will receive all events related to that session at your webhook URL, allowing you to react to what your end users are doing in real time. Whenever something of interest happens in sessions that you have initiated with ZignSec, a webhook is fired off by ZignSec. In the next section, we'll look at how to consume webhooks. ## Consuming webhooks When your app receives a webhook request from ZignSec, check the `event` attribute to see what event caused it. ### Example webhook payload ```json { "event": "string", "id": "string", "integration_id": "string", "relay_state": "string", "result": { "errors": [], "status": "Finished", "eventSpecificData": { "field": "value" } }, "workflow_session_id": "string" } ``` In the example above, a conversation was `updated`, and the payload type is a `conversation`. --- ## Event types - `session_created` A new session was created. - `workflow_session_created` A new workflow session was created. - `session_updated`The state or data relating to a session was updated. - `workflow_session_state_updated`The state or data relating to a workflow was updated. > [!NOTE] > Each product may define its own session event and appropriate data structure, so please follow the product documentation for concrete integration. --- ## Security To know for sure that a webhook was, in fact, sent by ZignSec instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named X-ZignSec-Hmac- SHA256, and you can verify this signature by using your secret webhook key. The X-ZignSec-Hmac-SHA256 header included in each signed event contains a timestamp and one or more signatures. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme is v1. ZignSec generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, you should ignore all schemes that are not v1. --- ### Validating a Webhook Signature #### Step 1: Extract the timestamp and signatures from the header Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair. ##### Example Header Value ```bash {"X-ZignSec-Hmac-SHA256", "t=1658963065,v1=0b540e5072f3612e112f06bfdc85762fd4220502efc5846b3da4d0a235d5c019"} ``` The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). All other prefixes or schemes (if present) should be ignored. #### Step 2: Prepare the signed payload string Combine the timestamp (as a string) and the payload / request body using the character ‘.’ as a separator. ```bash payload_string="#{timestamp}.#{payload}" ``` Prepare the key combining or concatenating webhook-secret and merchantId received from ZignSec support (without any separators). ##### Example ``` bash HMAC_KEY = “webhook-secretb71357bc-d77c-4e3c-b678-84a10fe985ce” ``` #### Step 3: Compute a SHA256 HMAC digest for the array of bytes Compute HMAC digest ```bash hmac = :crypto.mac(:hmac, :sha256, HMAC_KEY, payload_string) ``` #### Step 4: Base 16 encode digest lowercase Base 16 Encode ```bash Base.encode16(hmac, case: :lower) ``` #### Step 5: Compare the base16 digest to the value of the X-ZignSec-Hmac-SHA256 header Computed digest must exactly match its corresponding header value. If there is no match, then the message may be compromised and it should not be trusted. Only one match is required.