Developers

Webhooks

The cAI webhooks allow you to integrate your system with the cAI platform to get notified about claim lifecycle changes. With this pattern you can easily keep your system / data models in sync with us.

Every configured webhook event will result in a POST request with a application/json content type being send to you. The target URL for each event type has to be configured in the cAI system. Please reach out to our onboarding team for that.

Note: Our webhook events are not fully finalized yet. Please expect changes to happen. We will make sure to not break your implementation and announce major changes upfront.

Data structure

All claim events that can occur will have the same data structure defined below.

Payload Description
type The event type
eventId The unique event id
date The timestamp when the event occured in UTC (ISO_8601)
source The internal cAI event source the event originates from (ESCALATION). <br> The field is optional and will be null if no source can be provided.
claim.id The unique claim identifier used by collectAI
claim.merchantId The merchantId the claim belongs to
claim.referenceNumber The claim reference number (provided by the merchant)
claim.action DEPRECATED The type of the event
claim.executedAt DEPRECATED Event execution time (ISO 8601)

Example request

POST /your-url HTTP/1.1

Body
{
  "type": "FEE_ADDED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": "ESCALATION",

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "DISPUTED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated
    ...
  }
}

Event Types

Disputed

When a dispute is triggered by the Debtor or Merchant, we will make a POST request to the configured URL for this claim dispute.

Body

In addition to the common claim wrapper information a disputeReason object will be provided when a dispute is triggered. It does contain justification for a dispute. It contains a type and an optional message for custom reasons. type can have one of the following values:

Dispute Reason Description
type Human friendly identifier of the dispute option (e.g DEBTOR_ALREADY_PAID)
message Message that was introduced when disputing the claim (only for type OTHER)
disputeId Unique identifier of the dispute

Example request

POST /your-url HTTP/1.1

Body
{
  "type": "DISPUTED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": null,

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "DISPUTED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "disputeReason": {
      "type": "DEBTOR_ALREADY_PAID"
    },
  },
}

When dispute reason is OTHER

POST /your-url HTTP/1.1

Body
{
  "type": "DISPUTED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": null,

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "DISPUTED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "disputeReason": {
      "type": "OTHER",
      "message": "I have a problem with my bank account."
    }
  }
}

Process Escalation

When a claim is being escalated and a debtor is contacted through a channel, we will make a POST request to the configured URL for claim escalation.

Body

The following information will be provided when a claim is escalated:

Payload Description
actionStep.id The id of the action step executed
actionStep.name The name of the action step executed
claim.communication.channel SMS, LETTER or EMAIL
claim.communication.reference Communication's unique identifier for future reference

Example payload

POST /your-url HTTP/1.1

Body
{
  "type": "ESCALATED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": "ESCALATION",

  "actionStep": {
    "id": 1482,
    "name": "Reminder Email 1",
  },

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "ESCALATED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "communication": {
      "channel": "SMS",
      "reference": "a6590eb9-497a-4a7f-b5df-xxxxxxxxxxxx"
    }
  }
}

Fee Added

When an fee is added to a claim, we will make a POST request to the configured URL for the fee addition.

Note: This event is only triggered if the escalation process adds a fee. You can also add fees with the API but this will not result in a webhook event.

Body

The following information will be provided when a fee was added:

Payload Description
actionStep.id The id of the action step executed
actionStep.name The name of the action step executed
claim.fee.id The id of the fee claim item.
claim.fee.type The item fee type. This can be either COLLECTION_FEE or DUNNING_FEE at the moment. More might be added in the future.
claim.fee.value The value of the fee in cents.
claim.fee.currency The currency of the fee's value, i.e. EUR

Example payload

POST /your-url HTTP/1.1

Body
{
  "type": "FEE_ADDED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": "ESCALATION",

  "actionStep": {
    "id": 1482,
    "name": "Reminder Email 1",
  },

  "claim": {
    "id": 54321,
    "merchantId" 1,
    "referenceNumber": "12345",
    "action": "FEE_ADDED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "fee": {
      "id": 9876,
      "type": "COLLECTION_FEE",
      "value": "2875",
      "currency": "EUR"
    }
  }
}

Payment In Progress

When a customer starts a payment process for the given claim, we will make a POST request to the configured URL for this.

Body

The following information will be provided when a payment is in progress inside the payment object:

Payload Description
claim.payment.providerName PSP that the user is using to start the payment
claim.payment.amount The amount in cents that the customer will pay
claim.payment.currency The currency of the payment, i.e. EUR
claim.payment.reference The reference of the payment, i.e. CAI-8373461
claim.payment.paymentRequestId Unique identifier of a payment flow

Example payload

POST /your-url HTTP/1.1

Body
{
  "type": "PAYMENT_IN_PROGRESS",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": null,

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "PAYMENT_IN_PROGRESS", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "payment": {
      "providerName": "FIGO",
      "amount": 1000,
      "currency": "EUR",
      "reference": "12345",
      "paymentRequestId": "c94e523f-45b8-4ab5-95e2-eae570188b18"
    }
  }
}

Payment Completed

When a customer concludes the payment process for the given claim, we will make a POST request to the configured URL for this.

Body

The following information will be provided when a payment is finished inside the payment object:

Payload Description
claim.payment.providerName PSP that the user is using to start the payment (FIGO, PAYPAL, WIRECARD, etc.)
claim.payment.amount The amount in cents that the customer will pay
claim.payment.currency The currency of the payment, i.e. EUR
claim.payment.transactionId Unique identifier of a completed transaction from the payment provider
claim.payment.paymentRequestId Unique identifier of a payment flow

Example payload

POST /your-url HTTP/1.1

Body
{
  "type": "PAYMENT_COMPLETED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": null,

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "PAYMENT_COMPLETED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "payment": {
      "providerName": "FIGO",
      "amount": 1000,
      "currency": "EUR",
      "transactionId": "7272hhd",
      "paymentRequestId": "c94e523f-45b8-4ab5-95e2-eae570188b18"
    }
  }
}

Claim Details Accessed

When a customer access the details of the claim (e.g. by opening the customer landing page), we will make a POST request to the configured URL for this.

Body

The following information will be provided when the user access the claim details inside the details object - note that the communicationType is only included if the access was traceable back to a communication channel.

Payload Description
claim.details.communicationType Type of the communication from which the customer accesed the claim details (SMS, EMAIL, etc.)
claim.details.channel Channel from which the customer accesed the details of the claim (LANDING_PAGE)
claim.details.sessionId Landing Page session which lasts from 1 hour, this is usefull for filter this type of event

Example payload

POST /your-url HTTP/1.1

Body
{
  "type": "DETAILS_ACCESSED",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": null,

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "DETAILS_ACCESSED", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "details": {
      "communicationType": "SMS",
      "channel": "LANDING_PAGE",
      "sessionId": "a4lSkLa8GOyfp5saix2xYEqGTJo95t-I"
    }
  }
}

Payment Modalities State Change

When a customer requests a payment modality or a merchant changes the status of such request, POST request is being triggered to notify about this.

Body

The following information will be provided inside the paymentModality object when payment modality is requested or state is changed:

Payment Modality Description
claim.paymentModality.type Type of a payment modality (PAYMENT_PLAN, PAYMENT_DEFEREMENT)
claim.paymentModality.state State of the payment modality request (REQUESTED, APPROVED, REJECTED)
claim.paymentModality.modalityId Payment modality identifier

Example payload

POST /your-url HTTP/1.1

Body
{
  "type": "PAYMENT_MODALITY_STATE_CHANGE",
  "date": "2018-08-24T11:32:23Z",
  "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
  "source": null,

  "claim": {
    "id": 54321,
    "merchantId": 1,
    "referenceNumber": "12345",
    "action": "PAYMENT_MODALITY_STATE_CHANGE", // deprecated
    "executedAt": "2018-08-24T11:32:23Z", // deprecated

    "paymentModality": {
      "type": "PAYMENT_PLAN",
      "state": "REJECTED",
      "modalityId": "646c684f-e77c-4448-9465-22677a66d18a"
    }
  }
}

Checkpoint reached

Whenever the claim has reached a custom configured marker step during it's lifecycle, we will make a POST request to notify about this.

This could be used to connect external processes into cAI's escalation, i.e. to add custom fees through the API.

Body

The following information will be provided when a checkpoint is reached

Payload Description
actionStep.id The id of the action step executed
actionStep.name The name of the action step executed

Example payload

POST /your-url HTTP/1.1

Body
{
 "type": "CHECKPOINT_REACHED",
 "date": "2018-08-24T11:32:23Z",
 "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
 "source": null,

 "actionStep": {
   "id": 1482,
   "name": "Reminder Email 1",
 },

 "claim": {
   "id": 54321,
   "merchantId": 1,
   "referenceNumber": "12345",
   "action": "CHECKPOINT_REACHED", // deprecated
   "executedAt": "2018-08-24T11:32:23Z", // deprecated

   "details": {
     "offset": 8,
     "message": "Configured custom free text",
   }
 }
}

Archived

Whenever the claim has not being collected after processing all escalation steps it will transition to an archive state, we will make a POST request to notify about this.

Example payload

POST /your-url HTTP/1.1

Body
{
 "type": "ARCHIVED",
 "date": "2018-08-24T11:32:23Z",
 "eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
 "source": null,

 "claim": {
   "id": 54321,
   "merchantId": 1,
   "referenceNumber": "12345",
   "action": "ARCHIVED", // deprecated
   "executedAt": "2018-08-24T11:32:23Z" // deprecated
 }
}