Webhooks

As the Avenu API platform matures we will be implementing more and more Webhooks. As we release webhooks they will be added here, and announced in the Changelog.

Webhook	Description
Payments	Information about Payment status
Complaints	Information about customer Complaint status
Disputes	Information about Dispute status

Setup

1. Contact Avenu Support

Reach out to Avenu support via email, slack, or through the Partner Portal with a request to start receiving webhook notifications. The first thing we'll need is the URL to which you'd like the webhook notifications sent. Once we have received your URL, we'll implement the configuration in Avenu and securely provide you with a secretKey. Note that your URL should be configured to receive POST notifications. Examples of the payload format for notifications can be found below. It should respond with 2xx for success and 4xx for failures. At this time, notifications are not resent for failures.

2. Use the secretKey in your implementation to receive webhooks

When a webhook notification is sent, Avenu generates a hash value of the webhook data payload using the shared secretKey. This hash value is sent as a custom header "X-Signature". Avenu generates this hash value using HmacAlgorithms.HMAC_SHA_256 algorithm of HmacUtils.

From your end when the webhook notification is received, your application using the webhook data payload and the shared secret key calculates the signature using the same algorithm (HmacAlgorithms.HMAC_SHA_256) that Avenu used (See code example below). Then the calculated signature is used to verify the "X-Signature" header value.

public PaymentWebhookResponse processNotification(String key, String signature, String json, WebhookPaymentNotificationPayload notification) {
  // Check signature
  log.debug("Checking signature: {} with key: {}", signature, key);
  final String expectedSignature = signValue(key, json);
  if (expectedSignature == null) {
    return new PaymentWebhookResponse(false, "Bad signing key! Got: " + key);
  } else if (!expectedSignature.equalsIgnoreCase(signature)) {
    log.error("Bad signature using key: \"{}\"! Expecting: {}", key, expectedSignature);
    return new PaymentWebhookResponse(false, "Bad signature! Expecting: " + expectedSignature);
  }
  return new PaymentWebhookResponse(true, toResponseStatus(notification));
}
private String signValue(String key, String value) {
  try {
    return hmac.get(key, () -> new HmacUtils(HMAC_SHA_256, key)).hmacHex(value);
  } catch (Exception e) {
    log.error("Could not generate HMAC-SHA256 signature", e);
    return null;
  }
}

3. Test receiving webhook notifications

Once you're ready, create a test transaction and check your logs for receiving the notification. Please reach out to Avenu support if you run into any issues.

Payments

When payment status changes occur to any of the following payment types an update will be sent to the client's application:

ACH - Payment to/from an ACH account
Avenu - Payment between Avenu customers
Debit_Card_Fund - Denotes a debit card funding
ACH_TRANSFER - Denotes a payment created through the client/v1/transfer endpoint
TRANSFER_REFUND - Denotes a payment created through the client/v1/transferrefund endpoint

Available statuses are:

PENDING - A payment has been created and is waiting settlement. Current Balance has been updated
FAILED - A payment has not been created and is in a failed state
SETTLED - A created payment has been settled and Available Balance has been updated
DECLINED - A payment has been declined
CANCELED - A created payment has been canceled

Payment Status Webhook Notification Examples

Payment start webhook notification

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "ACH",
        "status": "PENDING",
        "transactionResponse": {
            "type": "PAYMENT",
            "description": "Payment transaction initiated",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment authorization approved notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "PENDING",
        "transactionResponse": {
            "type": "AUTHORIZED",
            "description": "Transaction Accepted",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment authorization declined notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction Declined, full address does not match",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment capture approved notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "PENDING",
        "transactionResponse": {
            "type": "CAPTURED",
            "description": "Transaction Accepted",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment capture declined notification (debit fund)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction Declined",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment sub-ledger update notification (PENDING)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "PENDING",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction updated",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment sub-ledger update notification (SETTLED)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "DEBIT_CARD_FUND",
        "status": "SETTLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction updated",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment account name verification failed notification (ACH)

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "ACH",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "surnameMatch NO,givenNameMatch NO",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Payment fraud check failed notification

{
  "type": "payment",
  "created_at": "2021-12-07",
  "data": {
    "customer": {
        "accountNumber" : "12345"
    },
    "transaction": {        
        "id": "12345abc",
        "type": "ACH",
        "status": "CANCELLED",
        "transactionResponse": {
            "type": "TRANSACTION",
            "description": "Transaction got declined. Please contact a system administrator.",
            "dateUpdated": "2021-12-07"
        }        
    }
  }
}

Complaints

When a customer submits a Complaint through the complaint endpointAvenu will push a notification through the client-configured Webhook URL .

Webhook notification complaint payload data

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "CONCERN",
        "status": "CREATED",
        "transactionResponse" : {
          "type": "SUCCESS",
          "description": "Concern created in Case Management Tool",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Alert Creation Failed

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "CONCERN",
        "status": "CREATED",
        "transactionResponse" : {
          "type": "FAILED",
          "description": "Complaint Not created in Case Management Tool - Contact Support",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Alert Created In Avenu

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "CONCERN",
        "status": "RECEIVED",
        "transactionResponse" : {
          "type": "SUCCESS",
          "description": "Avenu received the complaint",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Alert Created In Case Management Tool

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "CONCERN",
        "status": "CREATED",
        "transactionResponse" : {
          "type": "SUCCESS",
          "description": "Concern created in Case Management Tool",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Additional Information Needed

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "CONCERN",
        "status": "INFORMATION_NEEDED",
        "transactionResponse" : {
          "type": "",
          "description": " + please have the customer reach out directly to collect the information",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Customer Concern Completed

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "CONCERN",
        "status": "COMPLETED",
        "transactionResponse" : {
          "type": "",
          "description": "",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Complaint Response Completed

{
  "type": "concern",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
      {
        "accountNumber": "12345"
      }
    ],
    "transaction": [
      {
        "id": "12345abc",
        "type": "COMPLAINT",
        "status": "COMPLETED",
        "transactionResponse" : {
          "type": "",
          "description": "",
          "dateUpdated": "2021-12-07T00:21:40.670058Z"
        }       
      }
    ]
  }
}

Disputes

When a customer submits a Dispute through the disputes endpoint and as updates happen within the compliance monitoring system Avenu will push a notifications through the client-configured Webhook URL .

Webhook notification dispute payload data - RECEIVED

{
  "type": "dispute",
  "data": {
    "customer": {
      "accountNumber": "6313280146131087"
    },
    "transaction": {
      "id": "6f42051e-3e0b-4a30-b7b7-928ff0da3096",
      "type": "UNAUTHORIZED",
      "status": "RECEIVED",
      "transactionResponse": {
        "type": "UNAUTHORIZED",
        "description": "Dispute has been received by Avenu - pending review",
        "dateUpdated": "2024-05-07T23:03:24Z"
      }
    }
  },
  "created_at": "2024-05-07T23:03:25.271972Z"
}

Webhook notification dispute payload data - Dispute alert CREATED

{
  "type": "dispute",
  "data": {
    "customer": {
      "accountNumber": "6313280146131087"
    },
    "transaction": {
      "id": "6f42051e-3e0b-4a30-b7b7-928ff0da3096",
      "type": "UNAUTHORIZED",
      "status": "CREATED",
      "transactionResponse": {
        "type": "UNAUTHORIZED",
        "description": "Dispute has been created in the Compliance Monitoring System - pending review",
        "dateUpdated": "2024-05-07T23:03:24Z"
      }
    }
  },
  "created_at": "2024-05-07T23:03:25.271972Z"
}

Webhook notification dispute payload data - Dispute alert (Dispute not finalized, provisional credit)

{
  "type": "dispute",
  "data": {
    "customer": {
      "accountNumber": "6313280146131087"
    },
    "transaction": {
      "id": "6f42051e-3e0b-4a30-b7b7-928ff0da3096",
      "type": "UNAUTHORIZED",
      "status": "PROVISION_CREDIT",
      "transactionResponse": {
        "type": "DISPUTE_NOT_FINALIZED___PROVISION_CREDIT_NEEDED",
        "description": "Narrative as provided by compliance under text_entries.narrative field",
        "dateUpdated": "2024-05-07T23:03:24Z"
      }
    }
  },
  "created_at": "2024-05-07T23:03:25.271972Z"
}

Webhook notification dispute payload data - Dispute alert Completed (Dispute complete - error occurred)

{
  "type": "dispute",
  "data": {
    "customer": {
      "accountNumber": "6313280146131087"
    },
    "transaction": {
      "id": "6f42051e-3e0b-4a30-b7b7-928ff0da3096",
      "type": "UNAUTHORIZED",
      "status": "COMPLETED",
      "transactionResponse": {
        "type": "DISPUTE_FINALIZED___ERROR_OCCURRED",
        "description": "Narrative as provided by compliance under text_entries.narrative field",
        "dateUpdated": "2024-05-07T23:03:24Z"
      }
    }
  },
  "created_at": "2024-05-07T23:03:25.271972Z"
}

Webhook notification dispute payload data - Dispute alert Completed (Dispute complete - No error occurred)

{
  "type": "dispute",
  "data": {
    "customer": {
      "accountNumber": "6313280146131087"
    },
    "transaction": {
      "id": "6f42051e-3e0b-4a30-b7b7-928ff0da3096",
      "type": "UNAUTHORIZED",
      "status": "COMPLETED",
      "transactionResponse": {
        "type": "DISPUTE_FINALIZED___NO_ERROR_OCCURRED",
        "description": "Narrative as provided by compliance under text_entries.narrative field",
        "dateUpdated": "2024-05-07T23:03:24Z"
      }
    }
  },
  "created_at": "2024-05-07T23:03:25.271972Z"
}