• Select

  • Select

Configure Webhooks

Using Fusion webhook APIs, you can set up a webhook against the available Fusion event types. This article will enable you to understand how to set up a webhook to be able to receive an event notification about important business process flows.

Note: Keep a webhook URL ready that can receive JSON objects and support basic HTTP authentication. Share this endpoint with Zeta. Zeta will register the webhook endpoint in Fusion and share a secret token with you to validate the incoming webhook messages.

Select an Event

Before creating a webhook, let’s find out Fusion topics and events that are available for you to configure a webhook. See Fusion event for a list of topics/events that you can subscribe to.

Add a webhook

Set up your webhook to handle incoming event messages using /registerWebhookSubscription endpoint. Specify the event details in the body parameter.

To add a webhook against an event, use the following endpoint:

POSTapi/v1/ifi/{ifiID}/registerWebhookSubscription

Input parameters

  • subscriptionID: Required. Unique identifier of the event subscription.

  • topic: Required. Fintech-specific object to which the event is emitted from a business logic.

  • webhookURL: Required. Webhook endpoint to handle incoming webhook messages.

  • secret: Required. Secret token to validate the incoming webhook message. Zeta will share a secret token

Example

cURL Sample
Switch Theme
Expand More
Copy 
curl -X POST \
  https://fusion.preprod.zeta.in/api/v1/ifi/140827/registerWebhookSubscription \
  -H 'authorization: {{auth-token}} \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "subscriptionID": "aki98dfsb-asdnkj3eoqh-006kgur",
  "topic": "_tenant_140827_RESOURCE",
  "webhookURL": "https://yoursample.com/t/gffrp-1595524776/post",
  "secret": "Yjc3MDkxN3YYOWYzZmIzMjNkMjg1mQuC"
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy 
200 OK
401 Unauthorized
403 Forbidden
404 Not Found`
Code Copied

Test a webhook

After you have subscribed for an event notification (lets say, a payment and A2A transfer event) , simulate an Ecom, ATM or POS transaction and check the webhook endpoint for any possible notification. The webhook endpoint is the webhookURL you’ve configured in the previous step against a payment event/topic (topic). If you receive a webhook message, proceed to the next step to verify that the incoming message delivered from a secured Fusion endpoint.

Contact Zeta Support to simulate and test a payment webhook.

A new sample payment event would look something like this after the webhook configuration and subscription. Note the topic, name, eventID, source, origin and data objects in the payload below:

Example

Payment event received after configuring a webhook
Switch Theme
Expand More
Copy 
{
  "topic": "_tenant_140827_RESOURCE",
  "name": "RESOURCE_PAYMENT_CREATED",
  "eventID": "fc529204-126e-4b37-8308-02bdd1a29b52",
  "source": {
    "uri": "resource://140827/0c97e84f-999d-4fdf-a53f-24cb99b11e76/870544000001",
    "tags": [
      "tag://VBO/ABC001",
      "tag://VBO/ABC001"
    ],
    "state": "PAYMENT_REQUESTED"
  },
  "origin": {
    "instance": "instance://default/payment/870544",
    "time": 1582108024106,
    "flowID": "4807977e-fe36-4f03-be80-3b67dfbf23a9"
  },
  "data": {
    "paymentID": 870544000001,
    "currentState": "PAYMENT_REQUESTED",
    "stateTransitions": {
      "PAYMENT_REQUESTED": {
        "time": 1582108023741
      }
    },
    "payerInfo": {
      "resourceID": "0c97e84f-999d-4fdf-a53f-24cb99b11e76",
      "formFactorURI": "card://ff936322-287f-43e4-9497-a86d94bd97a9",
      "targetURI": "account://6b2dfb83-9276-422c-8781-07eda71fc261",
      "type": "RESOURCE"
    },
    "payeeInfo": {
      "type": "EXTERNAL_BUSINESS",
      "name": "TEST MERCHANT",
      "location": "MUMBAI"
    },
    "receipt": [],
    "attributes": {
      "super-card.trans-id": "M00001_T00001_111111_022030_486837818528_200219102702",
      "super-card.rrn": "486837818528",
      "super-card.ifi": "140827",
      "super-card.card-6x4": "508645-xxxxxx-0289",
      "super-card.merchant-country": "IN",
      "journal.voucherCode": "RUPAY-508645_ECOM_AUTH",
      "super-card.merchant-city": "MUMBAI",
      "super-card.acquirer": "111111",
      "super-card.acs-txnId": "028852720888773631103971827607",
      "super-card.merchant-lat": "18.975",
      "super-card.card-bin": "508645",
      "credentials.signatory": "[email protected]/1",
      "super-card.stan": "022030",
      "super-card.mid": "M00001",
      "super-card.tid": "T00001",
      "super-card.mcc": "5411",
      "super-card.merchant-lon": "72.825833",
      "super-card.txn-type": "ECOM",
      "super-card.otp-enter-mode": "manual",
      "supercard-card.authentication-type": "DYNAMIC_PIN",
      "super-card.merchant-name": "TEST MERCHANT",
      "super-card.card-id": "resource://0c97e84f-999d-4fdf-a53f-24cb99b11e76_ff936322-287f-43e4-9497-a86d94bd97a9",
      "super-card.ink": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36",
      "super-card.init-time": "200219102702"
    }
  },
  "publisher": {
    "appDomain": "services.fusion",
    "serviceName": "payment",
    "nodeId": "870544"
  }
}
Code Copied
A2A transfer event received after creating a payment transfer
Switch Theme
Expand More
Copy 
{
  "data": {
    "topic": "_tenant_140827_A2ATransfer",
    "name": "TRANSFER_CREATED",
    "eventID": "f62fa71f-7cc0-478d-b896-abf74e675e0f",
    "source": {
      "uri": "a2aTransfer://140827/c8b0ffbe-93f6-46a1-86e9-bb3213d42a38?publishingApp=fusion",
      "tags": [
        "tag://vbo-id/4fa18593-d2d9-4bf3-bea7-7f6deb9f2ca4?publishingApp=fusion"
      ],
      "state": "COMPLETED"
    },
    "origin": {
      "instance": "instance://default/fusion/295411",
      "time": 1590736346458,
      "flowID": "64e276bc-3908-43f7-978a-b58155da5127"
    },
    "data": {
      "ifiId": 140827,
      "transferRequest": {
        "requestID": "c8b0ffbe-93f6-46a1-86e9-bb3213d42a38",
        "currency": "INR",
        "amount": 1000000,
        "transferCode": "ATLAS_P2M_AUTH",
        "debitAccountID": "3867f3ac-fa4b-4f7c-859c-41bbeb586c45",
        "creditAccountID": "0e7381cc-a1f3-4af7-9a50-f120be76b1b8",
        "transferTime": 12324254832342,
        "remarks": "TEST",
        "attributes": {}
      },
      "transferResponse": {
        "requestID": "c8b0ffbe-93f6-46a1-86e9-bb3213d42a38",
        "transferID": "20200529071226316_28033_c8b0ffbe-93f6-46a1-86e9-bb3213d42a38",
        "status": "SUCCESS"
      }
    },
    "publisher": {
      "appDomain": "services.olympus",
      "serviceName": "fusion",
      "nodeId": "295411"
    },
    "emitterType": "EVENT"
  },
  "attributes": {
    "topic": "_tenant_140827_a2aTransfer"
  }
}
Code Copied

Validate a webhook

Ensure that you have already shared the webhook endpoint with Zeta. Zeta will register the webhook endpoint in Fusion platform.

You must verify every incoming event to ensure the messages are delivering from a secured Fusion endpoint. Zeta will share a secret token (used in above API call) with you to verify the authenticity of the message. Using the secret token, you can generate an HMAC (Hash-based Message Authentication Code) signature to match with the X-Zeta-HMAC that is passed in the header along with the event message.

To validate a webhook

You can use the ZetaHmacVerificationUtil class to validate the webhook:

Switch Theme
Expand More
Copy 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

import static com.google.common.hash.Hashing.sha256;
import static java.nio.charset.StandardCharsets.UTF_8;
 
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.annotation.Nonnull;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
 
public class ZetaHmacVerificationUtil {
  private static final String HMAC_SHA_512 = "HmacSHA512";
 
  /**
   * @param data - the raw bytes extracted from the received event body
   * @param secretBase64 - the secret shared by Zeta, Base64 encoded
   * @param nonce - the Nonce value from the HTTP header with the key X-Zeta-Nonce
   * @param incomingZetaHmac - the HMAC value extracted from the HTTP header with the key X-Zeta-HMAC
   * @return - true if the incoming HMAC is equal to the Zeta-computed HMAC, false otherwise
   */
  public static boolean verifyZetaHmac(
      @Nonnull byte[] data,
      @Nonnull String secretBase64,
      @Nonnull String nonce,
      @Nonnull String incomingZetaHmac) {
    return incomingZetaHmac.equals(computeZetaHmac(data, secretBase64, nonce));
  }
 
  /**
   * @param data - the raw bytes extracted from the received event body
   * @param secretBase64 - the secret shared by Zeta, Base64 encoded
   * @param nonce - the Nonce value from the HTTP header with the key X-Zeta-Nonce
   * @return - the Zeta-computed HMAC
   */
  public static String computeZetaHmac(byte[] data, String secretBase64, String nonce) {
    byte[] nonceBytes = nonce.getBytes(UTF_8);
    byte[] hmacDataWithNonce = computeHMAC512(data, hashSha256(nonceBytes));
    byte[] secretBytes = base64Decode(secretBase64.getBytes(UTF_8));
    return new String(base64Encode(computeHMAC512(hmacDataWithNonce, secretBytes)));
  }
 
  private static byte[] computeHMAC512(byte[] data, byte[] secret) {
    try {
      final Mac sha512_HMAC = Mac.getInstance(HMAC_SHA_512);
      final SecretKeySpec keySpec = new SecretKeySpec(secret, HMAC_SHA_512);
      sha512_HMAC.init(keySpec);
      return sha512_HMAC.doFinal(data);
    } catch (NoSuchAlgorithmException | InvalidKeyException e) {
      throw new RuntimeException("FAILED_TO_COMPUTE_HMAC");
    }
  }
 
  private static byte[] hashSha256(byte[] toHash) {
    byte[] hash = new byte[32];
    sha256().hashBytes(toHash)
        .writeBytesTo(hash, 0, 32);
    return hash;
  }
 
  private static byte[] base64Decode(byte[] bytes) {
    return Base64.getDecoder().decode(bytes);
  }
 
  private static byte[] base64Encode(byte[] bytes) {
    return Base64.getEncoder().encode(bytes);
  }
}
Code Copied

  1. Extract the raw bytes from the received event body

  2. Extract the Nonce value from the HTTP header with the key X-Zeta-Nonce

  3. Extract the HMAC value from the HTTP header with the key X-Zeta-HMAC

  4. Invoke the verifyZetaHmac function of the ZetaHmacVerificationUtil class, with the arguments data (from step 1), base64EncodedSecret (shared by Zeta), nonce (from step 2), hmac (from step 3). The method returns true if the incoming HMAC is equal to the Zeta-computed HMAC, and false otherwise. If the method returns true, you can consider the event message is valid and sent over secured Fusion connection. If it returns false, reject the message and report to Zeta for further analysis.

  5. Alternatively, you can invoke ZetaHmacVerificationUtil#computeZetaHmac with the data from steps 1 and 2, along with the secret token shared by Zeta, to generate the HMAC on your own. Compare the generated HMAC with the extracted HMAC (from step 3). If both are identical, the message is valid and authentic.

Contact Zeta Support to obtain the secret token or any help to validate a payment webhook.

Related articles

Fusion Events

List of webhooks to subscribe to & receive event notification

About webhooks

Know about key concepts around webhooks and event configuration