Webhooks

You can setup webhooks to get notified in your application whenever a Payment or Approval Object of yours changes state, or when new ones are created. You can receive notifications for both Payment and Approval Objects via the same webhook, or you can create seperate webhooks for each type, as described .

To setup a webhook, you must first create an HTTP POST endpoint in your application which accepts the JSON notification payload in the format shown below. The endpoint must return a successful status code (200) as quickly as possible, prior to any complex logic that could cause a timeout.

{
    "id":123,
    "type":"APPROVAL_OBJECT"
    "state":"PROCESSED"
}

The notification contains the id of the object, the type of the object and the current state of the object.

The type of the object can either be APPROVAL_OBJECT or PAYMENT_OBJECT.

The state of the can be FAILED | PENDING_APPROVAL | PENDING_COMPLIANCE_CHECKS | PENDING_PAYMENT | PENDING_SIGNING | PROCESSED | PROCESSING_IBAN | REJECTED_APPROVAL | REJECTED_COMPLIANCE | REJECTED_SIGNING.

If the type of the object it PENDING_COMPLIANCE_CHECKS it means that it is a new object that has been created, which is now pending compliance checks.

Once your endpoint is setup, it can be registered to ZTLment using the Create Payment Webhook endpoint. The 'object_type' of the payload is an array for specifying what type of objects you want to be notified about, e.g.: [PAYMENT_OBJECT, APPROVAL_OBJECT]. This completes the setup to receive real-time notifications directly to this endpoint.

Webhook signatures:

ZTLment always signs the webhook notification it sends to your endpoint by including an X-Payload-Signature header with the signature of the payload. We recommend you to use the signatures to verify that the webhook request didn’t come from a malicious server but was actually generated by ZTLment.

4 steps to verify a webhook request comes from ZTLment:

1. Retrieve the X-Payload-Signature header.
2. Retrieve the webhook HTTP body as bytes.
3. Generate a signature by signing the body from step 2 with the secret key that is generated when creating a webhook. It is important to note that all signing must be done using the HmacSHA512 algorithm.
4. Verify that the X-Payload-Signature header from step 1 matches the signature generated in step 3.

Below is an example of how this could be done in Java:

@ResponseBody
@PostMapping(produces = MediaType.APPLICATION_JSON_VALUE, value = "https://youcompany.com/payment-webhook-consume", consumes = MediaType.APPLICATION_JSON_VALUE)
public void consumeData(@Valid @RequestBody byte[] body, @RequestHeader(name="X-Payload-Signature") String signature) throws NoSuchAlgorithmException, InvalidKeyException {
    String ALGORITHM = "HmacSHA512";
    String SECRET = "<YOUR_WEBHOOK_SECRET_KEY>";
    SecretKey key = new SecretKeySpec(SECRET.getBytes(UTF_8), ALGORITHM);

    Mac mac = Mac.getInstance(ALGORITHM);
    mac.init(key);

    byte[] bSignature = mac.doFinal(body);
    String sSignature = Base64.encodeBase64String(bSignature);
    boolean isValid = sSignature.equals(signature);
}