Setting up your Webhook Endpoint

A webhook allows you to listen to events on your OpenCard account.

📘

Available webhooks

You can read more about the available webhooks here.

Begin using webhooks with your OpenCard integration in just three steps:

1. Create a Webhook Endpoint on your server.
First you need to create a webhook endpoint on your server. The endpoint needs to be able to handle both GET requests and POST requests using the same URL. GET requests is to support the OpenCard challenge request and POST is to receive the actual webhook event.

2. Handle the challenge
The OpenCard webhooks will send challenges to make sure your webhook is live and that you are the owner of the webhook. The challenge is a GET request to your endpoint with a challenge query parameter:

<your_webhook_url>?challenge=<random_string_challenge>

You need to add the x-verify-token header in the response with a calculated hmac sha256. Example:

$xVerifyToken = hash_hmac('sha256', <random_string_challenge>, <webhook_secret>)

var crypto = require('crypto');
var hmac;

hmac = crypto.createHmac('sha256', <webhook_secret>);
hmac.update(<random_string_challenge>);
xVerifyToken = hmac.digest('hex');

using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(<webhook_secret>))) 
{ 
  string xVerifyToken = BitConverter.ToString(hmac.ComputeHash(Encoding.UTF8.GetBytes(<random_string_challenge>))).Replace("-", 
  "").ToLower(); 
}

The webhook secret is found on the connection tab of each organization.

3. Handle the webhook event
All webhook events are sent as POST requests. Each event has the same setup of request header values of webhook. The header X-Event identifies the type of event (you can read more about the available webhooks here).

"Content-Type": "application/json",  
"X-Version": "<Version of the webhook, current active version is 1>",  
"X-Event": "<Type of event>",  
"X-Data-Signature": "<Signature of the event>"

a. Security

The first thing you need to do is to authenticate the webhook request. OpenCard supports multiple ways of securing your endpoint, you can find more information here. This is so that you can verify that the request is sent from OpenCard and that it is safe to process.

b. Process the request

The main job in processing the request is mapping webhook event data to you internal format. You can read more about the format here.

4. Test that your endpoint works
Go to the admin portal and your webhook settings, select to test that your endpoint works by testing each event you want to use.

📘

Queuing

If we receive anything else than a 200 or 201 response, we will repeat posts 3 times. If none of the 3 retries works all events will be queued until your endpoint is up an running again.

📘

Live transactions

You need a TPA, which you will get via your OpenCard application portal.
The TPA releases the transactions for a certain company/organization.