Webhooks

Webhooks allows you to receive notifications in your own backend whenever a payment objects changes state (see visual in the Payments page ) so that you can reflect any changes in your own backend. This guide will describe how to setup a webhook and verify the integrity of the notification.

Webhook Setup and Verification Guide

Setting Up a Webhook

To set up a webhook, follow these steps:

1. Create an HTTP POST endpoint in your application that accepts JSON notification payloads in the format shown below. The endpoint must return a successful status code (200) as quickly as possible, before performing any complex logic that could cause a timeout.

   JSON

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

2. Understand the notification payload:

   • id: The unique identifier of the object.
   • type: PAYMENT_OBJECT.
   • state: The current state of the object (see Payments page). Possible states include:
     - PENDING_COMPLIANCE_CHECKS
     - REJECTED_COMPLIANCE
     - PENDING_APPROVAL
     - REJECTED_APPROVAL
     - PENDING_SIGNING
     - REJECTED_SIGNING
     - PENDING_PAYMENT
     - INITIATED_PAYMENT
     - PROCESSING_PAYMENT
     - PROCESSED
     - FAILED
     - REVERSED

3. Register your endpoint with ZTLment using the Create Payment Webhook endpoint.

Note: If the state is PENDING_COMPLIANCE_CHECKS, it indicates that a new object has been created and is pending compliance checks.

Webhook Signatures

ZTLment signs every webhook notification it sends to your endpoint by including an X-Payload-Signature header with the payload's signature. It is recommended to use these signatures to verify that the webhook request is legitimate and was generated by ZTLment.

Steps to Verify a Webhook Request

1. Retrieve the X-Payload-Signature header from the request.
2. Retrieve the webhook HTTP body as bytes.
3. Generate a signature by signing the body from step 2 with the secret key generated when creating the webhook. Use the HmacSHA512 algorithm for signing.
4. Verify that the X-Payload-Signature header matches the signature generated in step 3.

Below is an example implementation in Java:

@ResponseBody
@PostMapping(produces = MediaType.APPLICATION_JSON_VALUE, value = "https://yourcompany.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(StandardCharsets.UTF_8), ALGORITHM);

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

    byte[] calculatedSignature = mac.doFinal(body);
    String calculatedSignatureString = Base64.getEncoder().encodeToString(calculatedSignature);
    boolean isValid = calculatedSignatureString.equals(signature);

    if (isValid) {
        // Process the webhook payload
    } else {
        // Handle the invalid signature
    }
}

By following these instructions, you can ensure that your application receives and verifies webhook notifications securely and efficiently.