Usage

Web hooks can be configured for any account. If a web hooks is NOT configured, Trice will search for the account's parent account and distribute the web hook to the parent if the parent has a web hook configured.

If a web hook fails and the receiver does not respond with a 20X code, the web hook will be attempted again at the following cadence for up to 5 re-tries:

📘

Web Hook Re-try Schedule

re-tryseconds after original web hook
110
2100
31000
410000
5100000 (1.15 days)

1 web hook can be created of each type. Five different types of web hooks can be created:

  • rtp_transfer_inbound - triggers on all inbound transfer state changes listed below
  • rtp_transfer_outbound - triggers on all outbound transfer state changes listed below
  • rtp_rfp_outbound - triggers on all request for payment state changes listed below
  • rtp_rfp_inbound - triggers on all request for payment state changes listed below
  • rtp_rfp_presentment - triggers on all request for payment presentment state changes listed below
  • account - triggers on all status or hold_details changes for an account or on account creation if status returns on_hold
  • person - triggers on all status or hold_details changes for a person or on person creation if status returns on_hold
  • party - triggers on all status or hold_details changes for a party or on party creation if status returns on_hold
  • default - if it is defined, it will trigger on any undefined web hook type

Trice will include the X-TRICE-WEBHOOK-TYPE header in the PUT which contains the web hook type associated with the web hook:

📘

Web Hook Type Header

X-TRICE-WEBHOOK-TYPE: rtp_transfer_inbound

Trice will include the X-TRICE-WEBHOOK-URI-ACCOUNT header in the PUT which contains the account id associated with the web hook URI being used:

📘

Web Hook URI Account Header

X-TRICE-WEBHOOK-URI-ACCOUNT: 669774a5-dbbc-481f-99ab-8c7c99d57766

Trice will include the X-TRICE-ACCOUNT header in the PUT which contains the account id associated with the web hook action:

📘

Web Hook Account Header

X-TRICE-ACCOUNT: 669774a5-dbbc-481f-99ab-8c7c99d57777

Trice will include the X-TRICE-SIGNATURE header in the PUT which contains a Base64 formatted HMAC-SHA256 signature of the PUT body content when sending a request to the web hook:

📘

Web Hook Signature Header

X-TRICE-SIGNATURE: qnq3xgpq5e5HuDGcASNNCHCoCi4qO9iSveSZ1yW0eZA=

Header value calculation:

Base64(
    HMAC-SHA256(
         YourSecretKey,
         X-TRICE-ACCOUNT_value+
         X-TRICE-WEBHOOK-URI-ACCOUNT_value+
         X-TRICE-WEBHOOK-TYPE_value+
         PUT_body_content
    )
  );

Your secret_key will only be returned in the POST to create the webhook. All subsequent GET calls will have the secret_key as null.

Web hooks will be Restful PUT to your defined web hook uri on status changes of these objects

  • RTP Transfer status
  • RTP RfP Presentment status
  • RTP RfP status

The PUT content will be the JSON object of the rtp_transfer if the web hook type is rtp_transfer_inbound or rtp_transfer_outbound.

The PUT content will be the JSON object of the rtp_rfp if the web hook type is rtp_rfp_outbound or rtp_rfp_inbound.

The PUT content will be the JSON object of the rtp_rfp_presentment if the web hook type is rtp_rfp_presentment.

State changes that trigger web hooks

Outbound and Inbound RTP transfers

For rtp_transfers, the following state changes will trigger a web hook:

  • rejected - final state
  • failed - final state
  • timed_out - final state
  • completed - final state, with the exception of returned
  • returned - final state

Outbound and Inbound RTP Request for Payment

For rtp_rfps, the following state changes will trigger a web hook:

  • rejected - final state
  • failed - final state
  • timed_out - final state
  • approved
  • paid - final state
  • declined - final state
  • expired - final state
  • canceled - final state
  • waiting

RTP Request for Payment Presentments

For rtp_rfp_presentments, the following status changes will trigger a web hook:

  • reviewed
  • approved - final status
  • denied - final status
  • on_hold

account, person, and party

For account, person, party the following status changes will trigger a web hook:

  • on_hold - any change in status, including initial creation
  • hold_details - any updates, including initial creation