Webhook Overview

Webhooks allow the system to push notifications of particular system events without the Partner having the submit repeated requests for information. A Partner can parse pre-defined event types to obtain the information needed for operational management, errors, and reconciliation activity.

A Partner can establish up to three webhook endpoints, with one considered "primary" and the others "secondary". Only the primary endpoint will be used to send notifications. If the API cannot reach the primary webhook endpoint, the secondary endpoints can be used as a failover. Any of the submitted endpoints can be set to a status of "primary". Primary endpoints cannot be deleted unless it is the only endpoint defined for the Partner account.

HTTP callback events are asynchronous and the order of calls is not guaranteed to match the exact timeline of events that occurred across Convera internal systems. Events are triggered by changes in the state of a resource, such as a change in payment status, or triggered by a Partner action, such as a Send Ping Request request.

When an event occurs, the registered endpoints will be transmitted to using a HTTP POST method with a pre-defined JSON payload based on the type of event. All calls will transmit using SSL encryption and the Partner should provide HTTPS-ready endpoints to uphold security.

Each call will include an access token provided by the partner in the response header e.g. Authorization: WUBS_API partnerProvidedAccessToken

Handling Callbacks

It is a best practice to handle received callback in asynchronous manner to reduce possibility of timeouts. Another good practice is to design the receipt of the event as idempotent. This ensures that if the same event is received more than once, any duplicate callbacks will not cause adverse impact.

Callbacks sent from the Convera API will be considered accepted if a 200 or 201 HTTP status code is received. Any header values or payload in a response will be ignored. If any other status code is received, Convera will continue to send events for a period of time and will eventually place events into an unresolved error queue.

Event Types

An event payload will be defined as a combination of common and resource-specific fields. Common fields are present in all webhook responses, whereas resource-specific fields will differ depending on the event and state of the resource.

{
  "id":	string,
  "createOnUtc": timestamp,
  "eventType": string,
  "summary": string,
  "resource": {}
}

Currently Supported Event Types

ping

A ping event is triggered whenever a ping request is triggered from the Partner account. This is useful for testing and establishing connection to the webhook endpoints and for periodic health checks.

{
  "id": "2fa38c3d-11fc-4f58-8aee-b01965cbf789",
  "eventType": "ping",
  "createdOnUTC": "2022-01-07T16:15:17Z",
  "summary": "Ping request was successful."
}

payment.statusChanged

This event occurs whenever a payment progresses through one of the steps in the workflow. You can view all statuses in Payment Statuses the section.

The following webhook is for a payment moving to the Created status

{
  "id": "eacabcbf-a7fa-42f1-903a-6ae453a28931",
  "eventType": "payment.statusChanged",
  "createdOnUTC": "2022-01-07T16:30:06Z",
  "summary": "A payment status has been changed.",
  "resource": {
    "id": "123456789",
    "customerId": "customer_01",
    "partnerReference": "optional partner reference data",
    "status": "Created",
    "errorCode": null,
    "createdOn": "2022-01-07T16:30:03Z",
    "lastUpdatedOn": "2022-01-07T16:30:03Z",
    "isDoddFrank": "False",
    "outgoingOrderId": "Order123"
  }
}

The following webhook is for a payment moving to the Notice of Change status

{
  "id": "8de00f86-5573-4bfc-9e6d-94b4682bc648",
  "eventType": "payment.statusChanged",
  "createdOnUTC": "2022-01-14T00:31:04Z",
 "summary": "A payment status has been changed.",
  "resource": {
    "id": "Test_Demo_Payment2",
    "customerId": "MPCPLD",
    "partnerReference": "",
    "status": "NoticeOfChange",
    "errorCode": "C07 - 11111, 22222, savings",

    "NOC" : {
        nocCode : "C07",
        currentAccountNum: "82951344",
        proposedAccountNum: "11111",
        currentRoutingCode: "053904483",
        proposedRoutingCode: "22222",
        currentAccountType: "checking",
        proposedAccountType: "savings"
        },

    "createdOn": "2022-01-14T00:31:02Z",
    "lastUpdatedOn": "2022-01-14T00:31:02Z",
    "isDoddFrank": "False",
    "outgoingOrderId": "Order123"
  }
}

payment.notAccepted

Payments that are submitted but do not pass initial validation are rejected with a status of notAccepted. You can refer to the list of Error Codes to diagnose the reason for the rejection and attempt to resubmit the payment. A webhook response will be generated for each instance of a notAccepted payment.

{
  "id": "26514b59-83bd-4877-874c-fe127856ba2e",
  "eventType": "payment.notAccepted",
  "createdOnUTC": "2022-01-07T16:46:58Z",
  "summary": "A payment is not accepted for processing.",
  "resource": [
    {
      "id": "123456789",
      "customerId": "customer_01",
      "status": "NotAccepted",
      "errorCode": "1104"
    }
  ]
}

order.statusChanged

Similarly, when a payment order moves through workflow, a webhook response will be sent for each new status. You can view all Order Statuses here.

{
  "id": "0d577d40-b14b-41ad-8a34-b1990dc09132",
  "eventType": "order.statusChanged",
  "createdOnUTC": "2022-01-07T16:53:44Z",
  "summary": "An order status has been changed.",
  "resource": {
    "id": "ORD1234567",
    "customerId": "customer_01",
    "partnerReference": "optional partner reference data",
    "status": "Committed",
    "createdOn": "2022-01-07T16:53:39Z",
    "lastUpdatedOn": "2022-01-07T16:53:39Z",
    "settlementCurrency": "USD",
    "batchReference": "optional batch reference data"
  }
}

order.invoiceGenerated

Once the payment order has been received, a webhook response will be generated to indicate that the payment invoice has been generated. This response includes the order IDs associated with the invoice, as well as the name of the invoice file for reconciliation purposes. Invoice generation and receipt is configured at the time of Partner onboarding.

{
  "id": "25cf1560-5037-43f4-b38a-a9857a8f1f60",
  "eventType": "order.invoiceGenerated",
  "createdOnUTC": "2022-01-07T18:25:52Z",
  "summary": "Invoice has been generated.",
  "resource": {
    "orderIds": "ORD1234567",
    "invoiceFileName": "invoice_2022-01-07.pdf"
  }
}

payment.updateFailed

Currently, updates to payments that have entered Created status are unable to be updated or changed. In the case an update is pushed to these payments, a webhook response will be generated.

{
  "id": "4103ecb9-983e-4331-bc42-b3a0801d0121",
  "eventType": "payment.updateFailed",
  "createdOnUTC": "2022-01-07T16:46:57Z",
  "summary": "A payment update has failed.",
  "resource": {
    "id": "123456789",
    "customerId": "customer_01",
    "status": "Created",
    "lastUpdatedOn": "2022-01-07T16:30:03Z",
    "updateErrorCode": "1104",
    "updateErrorOn": "2022-01-07T16:46:57Z"
  }
}

settlement.statusChanged

Triggered whenever a settlement activity occurs for any orders under partner account.

{
    "id": "ff09d885-3624-4d1f-9ed0-79d02984e6c8",
    "eventType": "settlement.statusChanged",
    "createdOnUTC": "2022-01-21T05:55:24Z",
    "summary": "A Settlement status has been changed.",
    "resource": {
        "id": "123456789",
        "customerId": "customer_01",
        "batchId": "batch_01",
        "createdOn": "12/9/2021 11:14:53 AM",
        "lastUpdatedOn": "12/9/2021 11:14:53 AM",
        "settlementCurrency": "GBP",
        "lastdatereceived": "12/9/2021 11:14:53 AM",
        "amountreceived": "1.1",
        "amountdue": "5.58",
        "amount": "6.68"
    }
}