Webhooks

Whenever a KYC is initiated, we update the customer status and send the webhooks.

---

IP addresses to whitelist

Merchants should whitelist the following IP addresses:

Environment	IP address
Stage	34.87.148.68
Prod	35.240.227.82

---

Validate webhook authenticity

Once the merchant receives the webhook call, we first request the merchant to validate if the call is truly made by Zamp. In order to validate that, we request you to extract the header key X-ROMA-Signature and validate against the logic below. The message consists of comma separated string with values event id, resource type, event type.

The result of the code block below and the value present in the X-ZAMP-Signature key should match.

Example validation

const message = "merchant_uNR5Kc6a2zTdfqbLsDwxUZ_06_15,kyc,kyc_succeeded;
const sha_message = CryptoJS.SHA256(`${message}:${ROMA_SECRET}`);
const x_roma_signature = CryptoJS.enc.Base64.stringify(sha_message);

---

Webhooks for KYC

Example payload

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"kyc",
  "event_type": "active",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "status": "active",
    "customer_id":"",
    "comments":""
  }
}

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"kyc",
  "event_type": "failed",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "status": "failed",
    "customer_id":"",
    "comments":""
  }
}

resource_type / status values for Kyc webhook:

1. in_review - KYC is in review state
2. rfi_requested - RFI is requested for the KYC approval
3. failed - KYC is failed (due to AML hits, insufficient data)
4. active - KYC is active

---

Webhooks for Credits

Example payload

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"credit",
  "event_type": "in_review",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "reference_id": "ref_098fe343",
    "customer_id": "iihr42_2pyNY8ZxjZGLbU7i2HzNDf_04_03",
    "account_id": "iihr42_64yNY8ZxjZGLbU7i2HzNDf_05_06",
    "source_currency_code": "USD",
    "status": "in_review",
    "amount": 100
  }
}

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"credit",
  "event_type": "succeeded",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "reference_id": "ref_098fe343",
    "customer_id": "iihr42_2pyNY8ZxjZGLbU7i2HzNDf_04_03",
    "account_id": "iihr42_64yNY8ZxjZGLbU7i2HzNDf_05_06",
    "source_currency_code": "USD",
    "status": "in_review",
    "amount": 100
  }
}

resource_type / status values for Credit webhook:

1. in_review - Credit is in review state
2. failed - Credit is failed
3. succeeded - Credit Succeeded
4. rfi_requested - RFI is requested for the status approval

---

Webhooks for Whitelisting Status

Example payload

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"Whitelisting",
  "event_type": "succeeded",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "status": "succeeded",
    "customer_id":""
  }
}

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"Whitelisting",
  "event_type": "failed",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "status": "failed",
    "customer_id":""
  }
}

resource_type / status values for Whitelisting webhook:

1. in_review - Whitelisted resource is in review state
2. failed - Whitelisted resource is failed ( AML checks, Not first party for AED etc...)
3. active - Whitelisted resource is active

---

Webhooks for Payouts Status

Example payload

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"debit",
  "event_type": "initiated",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "reference_id": "ref_098fe343",
    "customer_id": "iihr42_2pyNY8ZxjZGLbU7i2HzNDf_04_03",
    "account_id": "iihr42_64yNY8ZxjZGLbU7i2HzNDf_05_06",
    "source_currency_code": "USD",
    "status": "initiated",
    "amount": 100,
    "comments":""

  }
}

{
  "event_id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
  "resource_type":"debit",
  "event_type": "succeeded",
  "event_data": {
    "id": "iihr42_z9oFU3w5EQEtiZbVspr7WP_06_02",
    "reference_id": "ref_098fe343",
    "customer_id": "iihr42_2pyNY8ZxjZGLbU7i2HzNDf_04_03",
    "account_id": "iihr42_64yNY8ZxjZGLbU7i2HzNDf_05_06",
    "source_currency_code": "USD",
    "status": "succeeded",
    "amount": 100,
    "comments":""
  }
}

resource_type / status values for Payouts webhook:

1. initiated - Payout is initiated
2. in_review - Payout is in review state
3. failed - Payout is failed
4. succeeded - Payout Succeeded
5. rfi_requested - RFI is requested for the status approval

---

Expected response and retries

We expect the merchant to return a HTTP 200 OK status in case they have received the message. In the absence of a HTTP 200 OK response, Zamp will retry the webhook with backoff exponential logic with a doubling delay. Retries will be done for a maximum of 24 hours.