Webhooks
Webhooks allow you to gain insight into the trustshare system in real-time. They can be used to keep the state of your own system inline with trustshare's, or be notified of asynchronous processes.
Due to the asynchonous nature of payments in general, it is advised to leverage webhooks to correlate events and the movement of funds with your own system and its processes.
In this section we will explore the process of registering and consuming webhooks and the types of events that the trustshare system will expose to your endpoints.
Registering webhooks
To register a new webhook, you need to have a URL in your app that we can call. You can configure a new webhook from the dashboard under the developer settings. You can set up as many webhook handlers as you want. This is useful whilst developing against the sandbox environment, to allow multiple developers to expose their own handlers.
Now, whenever something of interest happens in the system, a message is fired off by us. In the next section, we'll look at how to consume webhooks.
Consuming webhooks
When your app receives a webhook request from us, check
the type attribute to see what event caused it. The first part
of the event type will tell you the resource that was
effected by the event, e.g. an inbound, outbound, etc,
Our webhook events do not include any information that could be considered PII and therefore, will only provide resource identifiers which can then be retrieved from the API.
Example webhook payload
{
"id": "wh_evt_1d6a4ZAzda",
"type": "intent_confirmed",
"payload": {
"id": "intent_a6Abs421Ex"
}
}
In the example above, a Payment Intent was confirmed, and
the payload contains the relevant information for retrieving the intent from the API. Webhook
handlers should resond with a 200-like reponse code to acknowledge receipt. In the event
we receive a non-200-like response we will endeavour to retry sending the event over
the next few minutes.
Event types
The events that we expose are listed below. Please note that we can not guarantee the order in which you receive events so it is up to you to ensure messages are handled correctly, even out of order.
- Name
intent_confirmed- Type
- Description
A payment intent was successfully confirmed by the pariticpant on the UI.
- Name
intent_cancelled- Type
- Description
An existing payment intent was cancelled via API call.
- Name
checkout_initiated- Type
- Description
A checkout is initiated at the point a payment intent is confirmed.
- Name
checkout_failed- Type
- Description
A checkout has failed, usually due the payment method used.
- Name
checkout_cancelled- Type
- Description
A checkout was cancelled by the participant mid-flow.
- Name
checkout_rejected- Type
- Description
A payment was rejected by the card issuer, or source bank.
- Name
checkout_abandoned- Type
- Description
A checkout process has timed-out. Time-out durations may vary, depending on the payment method.
- Name
checkout_settling- Type
- Description
A checkout process has been completed by the participant and we are expecting funds to arrive.
- Name
checkout_settled- Type
- Description
Funds have been received and the full amount of the checkout has been reconciled into the project.
- Name
debit_scheduled- Type
- Description
A debit has been scheduled for future collection.
- Name
debit_executing- Type
- Description
A debit has initiated the collection of funds.
- Name
debit_settling- Type
- Description
A debit collection has been successfully initiated and we are expecting funds to arrive.
- Name
debit_settled- Type
- Description
A debit collection has been received and successfully reconciled.
- Name
debit_cancelled- Type
- Description
A scheduled debit has been cancelled, usually due to a revocation of the associated mandate.
- Name
debit_failed- Type
- Description
A debit collection failed at initiation, usually due to insufficient funds.
- Name
inbound_settled- Type
- Description
An inbound has been created and reconciled due to the receipt of funds into the system.
- Name
settlement_settled- Type
- Description
A settlement has received all its required funds.
- Name
settlement_executing- Type
- Description
A settlements funds have been, or are to be, released, however funds have not entirely left the system.
- Name
settlement_executed- Type
- Description
A settlements funds have physically released from the system.
- Name
transfer_executing- Type
- Description
A transfer is processing.
- Name
transfer_executed- Type
- Description
A transfer has finalised and the funds have moved.
- Name
transfer_cancelled- Type
- Description
A transfer has been cancelled via the API.
- Name
transfer_failed- Type
- Description
A transfer has failed to process.
- Name
outbound_awaiting_funds- Type
- Description
An outbound has been created before the required funds are available.
- Name
outbound_scheduled- Type
- Description
An outbound has been scheduled for a future date.
- Name
outbound_paused- Type
- Description
An outbound has been paused pending another process completion, such as participant verification. The reason for the pause can be found in the
pause_reason.
- Name
outbound_in_review- Type
- Description
An outbound is currently under review by our operations and compliance teams.
- Name
outbound_cancelled- Type
- Description
An outbound was cancelled.
- Name
outbound_failed- Type
- Description
An outbound failed to execute. The reason for the failure can be found in the
failure_reason.
- Name
outbound_executing- Type
- Description
An outbound is currently processing.
- Name
outbound_executed- Type
- Description
An outbound has finalised and the funds have physically left the system.
- Name
participant_verified- Type
- Description
A participant has completed a verification process and become verified.
- Name
payment_instrument_processing- Type
- Description
A payment instrument is processing.
- Name
payment_instrument_enabled- Type
- Description
A payment instrument has been enabled for use in payment intents.
- Name
payment_instrument_disabled- Type
- Description
A payment instrument has been disabled.
- Name
payment_instrument_rejected- Type
- Description
A payment instrument has been rejected after processing.
- Name
payment_instrument_failed- Type
- Description
A payment instrument has failed creation.
- Name
payout_executing- Type
- Description
A payout from your revenue account is processing.
- Name
payout_executed- Type
- Description
A payout from your revenue account has finalised and the funds have physically left the system.
- Name
payout_failed- Type
- Description
A payout from your revenue account has failed to process. Contact support@trustshare.co.
- Name
verification_user_action_required- Type
- Description
A verification has been created and the flow is open and accessible to the user. The end-user needs to complete the verification process, i.e.: provide all requested information and go through the IDV selfie check at the end.
- Name
verification_in_review- Type
- Description
A verification is currently either being processed through our automated system or being reviewed by our compliance team. The user has completed the verification flow and has submitted all the information we need.
- Name
verification_passed- Type
- Description
A verification has been successfully reviewed and passed. The participant the verification belongs to is now verified and can receive funds.
- Name
verification_failed- Type
- Description
A verification has been reviewed and failed. The participant the verification belongs to, cannot yet receive funds.
Example payload
{
"id": "wh_evt_B16a4ZEQda",
"type": "checkout_initiated",
"payload": {
"id": "checkout_oIpJS127J2x",
"type": "local_bank_transfer",
"amount": 150000,
"intent_id": "intent_a6Abs421Ex",
"project_id": "project_87gAqx31z",
"participant_id": "participant_bNah32afl"
}
}
Security
You must provide a shared secret at the creation of a webhook
in the developer settings,
which will be supplied to your webhook handler in the x-trustshare-secret header.
Validating this shared secret allows you to confirm the authenticity of
the request to your endpoint. Here is an example of how to verify
the secret in your app:
Verifying a request
const secret = req.headers['x-trustshare-secret'];
if (process.env.TRUSTSHARE_WEBHOOK_SECRET === secret) {
// Request is verified
} else {
// Request could not be verified
}
It's essential to keep your webhook secret safe — otherwise, you can no longer be sure that a given webhook was sent by trustshare. Don't commit your secret webhook key to GitHub!