Webhooks Setup

To use webhooks, you need a server with an endpoint that can send and receive requests over HTTPS. Next, configure your webhook settings in your BlueSnap account. After setup is complete, you can simulate a webhook to test your configuration.

Webhooks are sent as POST requests that contain parameters that describe the event:

• For a list of available webhooks, refer to Webhook Name Reference.

• For descriptions of all parameters sent with each webhook, see Webhook Parameter Reference.

Step 1: Meet Server Requirements

🚧

SSL is Required

Your server must support HTTPS with a valid server certificate.

To receive and process webhooks, configure an endpoint on your server to listen for and respond to incoming webhooks from BlueSnap.

Request

BlueSnap sends webhooks in real-time as events occur. Your server should listen for these requests from BlueSnap. Webhook requests include the following HTTP header:

Content-type: "application/x-www-form-urlencoded"

Response

Your server should respond to each webhook with an empty HTTP 200 OK status code to acknowledge that you received the webhook. If BlueSnap does not receive this confirmation, we will retry the request up to 11 times.

BlueSnap IP addresses

Make sure your system is authorized to accept request from BlueSnap IP addresses. BlueSnap sends webhooks from these IP addresses only:

Step 2: Enabling Webhooks in BlueSnap

Configure your endpoint URL that receives webhooks and select which webhooks you want to enable to receive real-time updates on your transaction activity. You can configure multiple endpoints to receive different webhooks:

1. In the Merchant Portal, go to Settings > Webhook Settings.
2. Select Add Endpoint URL to view configuration options and the list of webhooks.
3. In Endpoint URL, enter the server endpoint that you configured to receive webhooks from BlueSnap. This URL must use the HTTPS protocol.
4. To enable a webhook, toggle the switch to its right so it displays blue and is switched to the right.
5. When you finish enabling webhooks, select Save.

To configure additional endpoints to receive webhooks, select Add Endpoint URL and repeat the steps in this section.

Adding a Security Header

You can add a security header to each webhook sent to your Endpoint URL. This feature adds two custom headers to each webhook request:

• bls-timestamp — Timestamp in the following format:
  bls-timestamp format

  YYYY-MM-DD HH:MM:SS.zzz
  

• bls-signature — Signature generated by concatenating the SHA-256 hash of bls-timestamp value with the webhook body in the following format:
  bls-signature format

  YYYY-MM-DD HH:MM:SS.zzz<webhook-body>
  

To add a security header:

1. In Security Header, toggle Add Security Header to the right to generate a unique encryption key that you can use to validate your webhook.
2. To verify a webhook was sent from BlueSnap, decrypt the bls-signature header with the encryption key that BlueSnap generated below Add Security Header. To generate a new encryption key, select the generate icon.

Step 3: Testing Webhooks

After you enable a webhook, select Test under Endpoint URL to verify that BlueSnap can connect to your endpoint URL.

📘

Note

A test webhook is an empty GET request. Before you test a webhook, ensure that your server can respond to GET requests.

Code Samples

The following Jakarata Server Pages (JSP) examples capture and log webhook data sent from BlueSnap. These webhook receiver examples verify that the webhook comes from BlueSnap servers, decode and parse the IPN, and then print the webhook to a log. There is a separate webhook receiver example for production and sandbox environments, with the relevant IP addresses per environment:

<%@page import="java.util.Arrays"%>
<%@page import="java.util.HashSet"%>
<%@page import="java.util.Set"%>
<%@page import="java.net.URLEncoder"%>
<%@page import="java.util.Map"%>
<%@ page language="java" contentType="text/html; charset=utf-8" pageEncoding="utf-8"%>

<%
String ipAddress = request.getRemoteAddr();

Set blueSnapIps = new HashSet(Arrays.asList("62.216.234.216, 209.128.93.254, 209.128.93.98, 38.99.111.60, 38.99.111.160, ..."));

if (blueSnapIps.contains(ipAddress)) {
  Map parameters = request.getParameterMap();

  for (String parameter : parameters.keySet()) {
		System.out.println("[" + parameter + "=" + java.net.URLDecoder.decode(parameters.get(parameter)[0], "UTF-8") + "]");
  }
} else {
	System.out.println(ipAddress + " is not a BlueSnap server!!!");
}
%>

<%@page import="java.util.Arrays"%>
<%@page import="java.util.HashSet"%>
<%@page import="java.util.Set"%>
<%@page import="java.net.URLEncoder"%>
<%@page import="java.util.Map"%>
<%@ page language="java" contentType="text/html; charset=utf-8" pageEncoding="utf-8"%>

<%
String ipAddress = request.getRemoteAddr();

Set<String> blueSnapIps = new HashSet<String>(Arrays.asList("209.128.93.232, 62.216.234.196. 38.99.111.50, 38.99.111.150, ..."));

if (blueSnapIps.contains(ipAddress)) {
  Map<String, String[]> parameters = request.getParameterMap();

  for (String parameter : parameters.keySet()) {
		System.out.println("[" + parameter + "=" + java.net.URLDecoder.decode(parameters.get(parameter)[0], "UTF-8") + "]");
  }
} else {
	System.out.println(ipAddress + " is not a BlueSnap server!!!");
}
%>