Guides
GuidesChangelog

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.

WebhookDescription
PaymentsInformation about Payment status
ComplaintsInformation about customer Complaint status
DisputesInformation about Dispute status
Customer StatusInformation about customer status updates

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 are the URLs to which you'd like the webhook notifications sent. We will configure a URL for each notification type (Payments, Customer Status, Complaints, and Disputes). Once we have received your URLs, we'll implement the configuration in Avenu and securely provide you with a secretKey. Note that your URLs 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
ACH_RETURN - A returned ACH transaction

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-07"
        }       
      }
    ]
  }
}

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-07"
        }       
      }
    ]
  }
}

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-07"
        }       
      }
    ]
  }
}

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-07"
        }       
      }
    ]
  }
}

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-07"
        }       
      }
    ]
  }
}

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": "Formal response to concern",
          "dateUpdated": "2021-12-07"
        }       
      }
    ]
  }
}

Webhook notification complaint payload data - Customer Concern Escalated to Complaint

{
  "type": "complaint",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "customer": [
    		{
      		"accountNumber": "12345"
    		}
     ],
    "transaction": [
    {
      "id": "12345abc",
      "type": "COMPLAINT",
      "status": "ESCALATED",
      "transactionResponse": {
        "type": "ESCALATED_TO_COMPLAINT",
        "description": "Concern has been escalated to a complaint internally",
        "dateUpdated": "2021-12-07"
        }       
      }
    ]
  }
}

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": "Formal response to complaint",
          "dateUpdated": "2021-12-07"
        }       
      }
    ]
  }
}

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-07"
      }
    }
  },
  "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-07"
      }
    }
  },
  "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-07"
      }
    }
  },
  "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-07"
      }
    }
  },
  "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-07"
      }
    }
  },
  "created_at": "2024-05-07T23:03:25.271972Z"
}

Customer Status

During customer onboarding when the customer status is updated Avenu will push a notifications through the client-configured Webhook URL .

Webhook notification customer status payload data - Customer In PENDING status

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345",
        "status": "PENDING",
        "transactionResponse" : {
          "type": "ONBOARDING_INITIATED",
          "description": "Customer Onboarding Initiated",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Webhook notification customer status payload data - Customer Onboarding Completed ENABLED status

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "accountNumber": "12345",
    "transaction": {
        "id": "12345abc",
        "status": "ENABLED",
        "transactionResponse" : {
          "type": "ONBOARDING_SUCCESS",
          "description": "Customer Onboarded Successfully",
          "dateUpdated": "2021-12-07"
        }       
      }
  }
}

Webhook notification customer status payload data - Customer Onboarding Completed DISABLED status

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345abc",
        "status": "DISABLED",
        "transactionResponse" : {
          "type": "ONBOARDING_FAILED",
          "description": "Customer Not Onboarded",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Webhook notification customer status payload data - ERROR

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "transaction": {
        "id": "12345abc",
        "status": "ERROR",
        "transactionResponse" : {
          "type": "CONTACT_SUPPORT",
          "description": "Unknown response received - contact customer support",
          "dateUpdated": "2021-12-07"
        }       
      }
  }
}

Webhook notification customer status payload data - Customer in ID_SCAN status

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345",
        "status": "ID_SCAN",
        "transactionResponse" : {
          "type": "IDSCAN_REQUIRED",
          "description": "Onboarding is pending",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Webhook notification customer status payload data - Photo ID Not Readable

NOTE for iFrame you will need to start the customer back at customer onboarding to obtain a new idScanUrl value.

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345abc",
        "status": "ID_SCAN",
        "transactionResponse" : {
          "type": "PHOTO_ID_NOT_READABLE",
          "description": "IDScan photo is not readable, please capture a new image and make an IDScan API call",
          "dateUpdated": "2021-12-07"
        }       
      }
  }
}

Webhook notification customer status payload data - IDScan Timed Out

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345abc",
        "status": "FAILED",
        "transactionResponse" : {
          "type": "IDSCAN_TIMED_OUT",
          "description": "IDscan time limit has expired, please reinitiate an Onboarding API call",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Webhook notification customer status payload data - Abandoned Session

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345abc",
        "status": "FAILED",
        "transactionResponse" : {
          "type": "ABANDONED_SESSION",
          "description": "Customer has abandoned the IDScan session, please reinitiate an Onboarding API call",
          "dateUpdated": "2021-12-07"
        }       
      }
  }
}

Webhook notification customer status payload data - Customer ID Scan Failure

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345abc",
        "status": "FAILED",
        "transactionResponse" : {
          "type": "IDSCAN_FAILURE",
          "description": "IDScan failed, please reinitiate an Onboarding API call",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Webhook notification customer status payload data - Customer in REVIEW status

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "id_number": "12345abc",
    "transaction": {
        "id": "12345",
        "status": "REVIEW",
        "transactionResponse" : {
          "type": "CUSTOMER_ONBOARDING_IN_REVIEW",
          "description": "Customer Onboarding In-Review",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Webhook notification customer status payload data - Customer account SUSPENDED

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "accountNumber": "12345",
    "transaction": {
      "id": "12345abc",
      "status": "DISABLED",
      "transactionResponse" : {
        "type": "CUSTOMER_ACCOUNT_SUSPENDED",
        "description": "Customer Account Suspended",
        "dateUpdated": "2021-12-07"
      }
    }
  }
}

Webhook notification customer status payload data - Customer account UNSUSPENDED (re-enabled)

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "accountNumber": "12345",
    "transaction": {
      "id": "12345abc",
      "status": "ENABLED",
      "transactionResponse" : {
        "type": "CUSTOMER_ACCOUNT_UNSUSPENDED",
        "description": "Customer Account Un-Suspended",
        "dateUpdated": "2021-12-07"
      }
    }
  }
}

Webhook notification customer status payload data - Customer account CLOSED

{
  "type": "customer_status",
  "created_at": "2021-12-07T00:21:40.670058Z",
  "data": {
    "newCustomerTag": "abcdefxxxxxx",
    "accountNumber": "12345",
    "transaction": {
        "id": "12345abc",
        "status": "DISABLED",
        "transactionResponse" : {
          "type": "CUSTOMER_ACCOUNT_CLOSED",
          "description": "Customer Account Closed",
          "dateUpdated": "2021-12-07"
        }       
      }    
  }
}

Updated 4 days ago