Fuse Webhooks Documentation

Configuring a webhook endpoint

A single URL for all webhooks can be configured in organisation settings in the Portal.
Webhook categories can be enabled/disabled from the settings
NOTE: Accounts, Payments, Transfers, Exchange Transfers are enabled by default

IP Addresses

Fuse webhooks are sent from the following IP addresses. These can be added to an allow list if required.

Sandbox	Production
15.185.183.112	16.62.35.28
157.241.63.92	16.63.177.47
157.241.38.195	16.63.180.53

Webhook retries

If posting a webhook returns a non-success status, then the webhook post is retried for up to 12 hours using an exponential backoff policy.

Fuse webhook structure

Headers

Fuse will send the following headers:

Field	Type	Description
X-Fuse-Timestamp	ISO-8601 Timestamp	Time that the webhook was sent to you. This will be in the following format: 2023-06-19T12:44:47Z.

Webhook body

Webhook bodies are encoded in JSON format with the following fields:

Field	Type	Description
type	string	Type of event
event_id	string	Id of the event in UUID format
event_version	integer	The webhook schema version
payload	Object (snake_case variant name)	Payload of the event nested under the variant name

Webhook Categories

Fuse webhooks are organized into five main categories. You can configure which categories of webhooks your organisation receives.

Categories Overview

Category	Description	Event Types
Account	Account lifecycle and updates	2 events
Payment	Local payment operations (inbound and outbound)	5 events
Transfer	Internal transfers between accounts	4 events
Exchange Transfer	Currency exchange operations between accounts	5 events
Onboarding	Customer onboarding status updates	2 events

Account Webhooks

Account opened

Sent when a new account has been opened.

Schema

Field	Title	Description
account_id	uuid	The account identifier in the Fuse system.
account_type	OneOf	The type of account. Possible values are primary, payment or virtual.
account_name	string	The name set on the account.
customer_id	uuid	The ID of the customer
external_id	string	External ID set when the account request is made.
currency	string	ISO currency code showing the currency of the account.

Example

{
  "type": "account_opened",
  "event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
  "event_version": 1,
  "account_opened": {
    "account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "account_name": "Contractors Inc.",
    "customer_id": null,
    "external_id": "01H2ZZV055MFPM8FD9RCJWM6R0",
    "currency": "AED",
    "account_type": "payment"
  }
}

Account updated

Sent when an account has been updated.

Schema

Field	Title	Description
account_id	uuid	The account identifier in the Fuse system.
account_name	string	The name set on the account.
account_owner	string	The owner name set on the account.
external_id	string	External ID set when the account request is made

Example

{
  "type": "account_updated",
  "event_id": "018c35ab-98bf-4390-bd51-858e61a87859",
  "event_version": 3,
  "account_updated": {
    "account_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "account_name": "Contractors Ltd.",
    "account_owner": "John Contractor",
    "external_id": "01H2ZZV055MFPM8FD9RCJWM6R0"
  }
}

Payment Webhooks

Outbound local payment created

A local payment has been initiated.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the outbound payment has been made.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
amount_with_fee	integer	The amount of the transaction in minor currency including the fee. E.g. 100 = 1.00.
instructed_amount	integer	The amount of the transaction as instructed without the fee in minor currency.
fee_amount	integer	The amount of fee incurred for the transaction in minor currency.
remitter	RemitterDetails	The details of the remitter of the payment.
beneficiary	BeneficiaryDetails	The details of the beneficiary of the payment.
purpose	PurposeCode	The purpose of the transaction. If this is unknown it is set to none.
currency	string	ISO currency code showing the currency of the payment.
external_reference	string	The reference as set by the customer when initiating the payment.
external_id	string	External ID that was set on the create payment request. If nothing was set this will be none.
timestamp	ISO8601 date time	The timestamp of when the event took place.
fee_source	FeeSourceAccount	Optional fee source account details.

Example

{
  "type": "outbound_local_payment_created",
  "event_id": "018c35b3-def3-a3bb-792d-f79534562555",
  "event_version": 4,
  "outbound_local_payment_created": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "instructed_amount": 51239,
    "amount_with_fee": 51239,
    "fee_amount": 0,
    "remitter": {
      "name": "Monday Inc.",
      "identifier": {
        "iban": "AE220910000000808720471"
      }
    },
    "beneficiary": {
      "name": "Fulan AlFulani",
      "identifier": {
        "iban": "AE120266712486572167372"
      }
    },
    "external_reference": "local*1701708016",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:40:29.683099191Z",
    "purpose": "goods_bought",
    "currency": "AED"
  }
}

Outbound local payment submitted

A local payment has been submitted for processing.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the outbound payment has been made.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
external_id	string	External ID that was set on the create payment request. If nothing was set this will be none.
timestamp	ISO8601 date time	The timestamp of when the event took place.

Example

{
  "type": "outbound_local_payment_submitted",
  "event_id": "018c35b3-e005-fd7b-ea42-aec8c20e521f",
  "event_version": 6,
  "outbound_local_payment_submitted": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:40:29.957851510Z"
  }
}

Outbound local payment executed

The local payment has been successfully processed.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the outbound payment has been made.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
external_id	string	External ID that was set on the create payment request. If nothing was set this will be none.
timestamp	ISO8601 date time	The timestamp of when the event took place.

Example

{
  "type": "outbound_local_payment_executed",
  "event_id": "018c35b4-030f-a403-dfe2-7c757e94f00b",
  "event_version": 7,
  "outbound_local_payment_executed": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "transaction_id": "018c35b3-def2-e645-1d5b-86be6746537b",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:40:38.927642874Z"
  }
}

Outbound local payment failed

The local payment attempt was unsuccessful.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the outbound payment has been made.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
timestamp	ISO8601 date time	The timestamp of when the event took place.
external_id	string	External ID that was set on the create payment request. If nothing was set this will be none.
failure_reason	OneOf (FailureReason)	Cause of failure while processing payment.

Example

{
  "type": "outbound_local_payment_failed",
  "event_id": "018c35b9-fbdc-8081-969a-bc591888d2e6",
  "event_version": 12,
  "outbound_local_payment_failed": {
    "account_id": "018c0027-a9b0-1f65-54ea-fe723844940f",
    "transaction_id": "018c35b9-8f58-9b36-370d-b5e3f00705ff",
    "failure_reason": {
      "bank_error": "Manual failure in Portal"
    },
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:47:10.300679370Z"
  }
}

Inbound local payment settled

An inbound local payment has settled into the account.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the inbound payment has been settled into.
transaction_id	uuid	The fuse transaction identifier for the inbound transaction.
amount_with_fee	integer	The amount of the transaction in minor currency including the fee. E.g. 100 = 1.00.
instructed_amount	integer	The amount of the transaction as instructed without the fee in minor currency.
fee_amount	integer	The amount of fee incurred for the transaction in minor currency.
remitter	RemitterDetails	The details of the remitter of the payment.
beneficiary	BeneficiaryDetails	The details of the beneficiary of the payment.
purpose	PurposeCode	The purpose of the transaction. If this is unknown it is set to none.
currency	string	ISO currency code showing the currency of the payment.
external_reference	string	The reference as set by the customer when initiating the payment.
timestamp	ISO8601 date time	The timestamp of when the event took place.
fee_source	FeeSourceAccount	Optional fee source account details.

Example

{
  "type": "inbound_local_payment_settled",
  "event_id": "018c35bc-9019-34b2-5210-ff9900d349bd",
  "event_version": 40,
  "inbound_local_payment_settled": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35bc-9086-638d-0e9a-f1f46ea6146a",
    "instructed_amount": 100000000,
    "amount_with_fee": 100000000,
    "fee_amount": 0,
    "remitter": {
      "name": "Topup",
      "identifier": {
        "iban": "AE080070000000785666509"
      }
    },
    "beneficiary": {
      "name": "AED Merchant Account",
      "identifier": {
        "iban": "AE460266386228195554412"
      }
    },
    "external_reference": "funding*1701708590",
    "timestamp": "2023-12-04T16:49:59.325104057Z",
    "purpose": "none",
    "currency": "AED"
  }
}

Transfer Webhooks

Internal transfer created

An internal transfer between two accounts has been initiated.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the transfer will be made from.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
amount	integer	The amount of the transaction in minor currency. E.g. 100 = 1.00.
to_account_id	uuid	The account identifier for the transfer destination.
reference	string	The reference as set by the customer when initiating the payment.
external_id	string	External ID that was set on the create internal transfer request. If nothing was set this will be none.
timestamp	ISO8601 date time	The timestamp of when the event took place.

Example

{
  "type": "internal_transfer_created",
  "event_id": "018c35ad-e939-11e1-b8ac-0896580ef2f6",
  "event_version": 38,
  "internal_transfer_created": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
    "amount": 1000000,
    "to_account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "reference": "transfer-1701707629",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:33:59.155913761Z"
  }
}

Inbound internal transfer settled

An internal transfer to the account has been completed and settled.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the inbound transfer is settling into.
from_account_id	uuid	The account identifier for the transfer source.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
timestamp	ISO8601 date time	The timestamp of when the event took place.
amount	integer	The amount of the transaction in minor currency. E.g. 100 = 1.00.
reference	string	The reference as set by the customer when initiating the payment.
external_id	string	External ID that was set on the create internal transfer request. If nothing was set this will be none.

Example

{
  "type": "inbound_internal_transfer_settled",
  "event_id": "018c35ad-e9ab-ae02-28a0-ebc9d3b70a89",
  "event_version": 3,
  "inbound_internal_transfer_settled": {
    "account_id": "018c355c-2413-16df-509f-40e71b142eb3",
    "from_account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e9ab-ae02-28a0-ebc9d3b70a89",
    "amount": 1000000,
    "timestamp": "2023-12-04T16:33:59.211640Z",
    "reference": "transfer-1701707629",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX"
  }
}

Internal transfer settled

A transfer from the account has been completed.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the transfer is settling from.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
external_id	string	External ID that was set on the create internal transfer request. If nothing was set this will be none.
timestamp	ISO8601 date time	The timestamp of when the event took place.

Example

{
  "type": "internal_transfer_settled",
  "event_id": "018c35ad-ea8e-031c-55ec-86af02893c79",
  "event_version": 39,
  "internal_transfer_settled": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX",
    "timestamp": "2023-12-04T16:33:59.211640Z"
  }
}

Internal transfer failed

An attempted internal transfer between two accounts was unsuccessful.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the transfer is settling from.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
timestamp	ISO8601 date time	The timestamp of when the event took place.
failure_reason	OneOf (FailureReason)	Cause of failure while processing transfer.
external_id	string	External ID that was set on the create internal transfer request. If nothing was set this will be none.

Example

{
  "type": "internal_transfer_failed",
  "event_id": "697cc542-aa22-4ee3-a278-949d59f24b15",
  "event_version": 44,
  "internal_transfer_failed": {
    "account_id": "018bfd91-ea86-a787-9d72-754cddfbc294",
    "transaction_id": "018c35ad-e939-eea5-d179-495d3fe1a783",
    "timestamp": "2023-12-04T16:33:59.211640Z",
    "failure_reason": {
      "bank_error": "Manual failure in Portal"
    },
    "external_id": "01JDHZK7QKF0WWQG43WNFQ3YCX"
  }
}

Exchange Transfer Webhooks

Outbound exchange transfer created

Currency exchange from one currency to another.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the exchange is settling from.
counterpart_account_id	uuid	The account identifier of where the exchange is settling to.
transaction_id	uuid	The fuse transaction identifier for the outbound exchange.
currency	string	The source currency of the exchange.
amount	integer	The amount of the source transaction in minor currency. E.g. 100 = 1.00.
counterpart_currency	string	The destination currency of the exchange
counterpart_amount	integer	The amount of the destination transaction in minor currency.
external_reference	string	The reference as set by the customer when initiating the exchange.
timestamp	ISO8601 date time	The timestamp of when the event took place.
rate	decimal	The exchange rate used to do the conversion.

Example

{
  "type": "outbound_exchange_transfer_created",
  "event_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
  "event_version": 29,
  "outbound_exchange_transfer_created": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "counterpart_account_id": "019342ec-af92-7470-9af9-7543cc6daf71",
    "transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
    "amount": 10000,
    "counterpart_amount": 36615,
    "external_reference": "reference-123",
    "timestamp": "2024-10-10T07:49:42.487717774Z",
    "currency": "USD",
    "counterpart_currency": "AED",
    "rate": 3.6615
  }
}

Outbound exchange transfer submitted

An exchange transfer has been submitted for processing.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the outbound exchange has been made.
transaction_id	uuid	The fuse transaction identifier for the outbound exchange.
timestamp	ISO8601 date time	The timestamp of when the event took place.

Example

{
  "type": "outbound_exchange_transfer_submitted",
  "event_id": "019482b0-871d-7d54-8346-a066ecc69221",
  "event_version": 30,
  "outbound_exchange_transfer_submitted": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
    "timestamp": "2024-10-10T07:49:54.649511283Z"
  }
}

Outbound exchange transfer executed

The outbound exchange transfer has been completed.

Schema

Field	Type	Description
account_id	uuid	The account identifier from where the outbound exchange has been made.
transaction_id	uuid	The fuse transaction identifier for the outbound exchange.
timestamp	ISO8601 date time	The timestamp of when the event took place.

Example

{
  "type": "outbound_exchange_transfer_executed",
  "event_id": "019482b0-871d-7d54-8346-a066ecc69221",
  "event_version": 31,
  "outbound_exchange_transfer_executed": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482b0-57d7-765c-bd23-2235f5d5aaab",
    "timestamp": "2024-10-10T07:49:54.649511283Z"
  }
}

Inbound exchange transfer settled

The inbound exchange transfer has settled into the destination account.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the exchange is settling into.
counterpart_account_id	uuid	The account identifier of where the exchange is settling from.
transaction_id	uuid	The fuse transaction identifier for the outbound exchange.
currency	string	The currency of the inbound exchange.
amount	integer	The amount of the inbound transaction in minor currency. E.g. 100 = 1.00.
counterpart_currency	string	The destination currency of the counterpart exchange
counterpart_amount	integer	The amount of the counterpart transaction in minor currency.
external_reference	string	The reference as set by the customer when initiating the exchange.
timestamp	ISO8601 date time	The timestamp of when the event took place.
rate	decimal	The exchange rate used to do the conversion.

Example

{
  "type": "inbound_exchange_transfer_settled",
  "event_id": "019482b0-8772-7a46-8792-73d9990dabd1",
  "event_version": 20,
  "inbound_exchange_transfer_settled": {
    "account_id": "019342ec-af92-7470-9af9-7543cc6daf71",
    "counterpart_account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482b0-873e-7f40-9ffe-1e3e298cbb10",
    "amount": 36615,
    "counterpart_amount": 10000,
    "external_reference": "reference-123",
    "timestamp": "2024-10-10T07:49:54.747094304Z",
    "currency": "AED",
    "counterpart_currency": "USD",
    "rate": 3.6615
  }
}

Outbound exchange transfer failed

The exchange transfer failed.

Schema

Field	Type	Description
account_id	uuid	The account identifier of where the transfer is settling from.
transaction_id	uuid	The fuse transaction identifier for the outbound transaction.
timestamp	ISO8601 date time	The timestamp of when the event took place.
failure_reason	OneOf (FailureReason)	Cause of failure while processing transfer.

Example

{
  "type": "outbound_exchange_transfer_failed",
  "event_id": "019482c7-c58d-7240-9850-9c76883b54cf",
  "event_version": 35,
  "outbound_exchange_transfer_failed": {
    "account_id": "01917542-1b7a-7c0c-a39b-17c96d0c7b53",
    "transaction_id": "019482c7-b534-7e55-a2f8-37ddb441866f",
    "failure_reason": {
      "bank_error": "Manual failure in Portal"
    },
    "timestamp": "2024-10-10T08:15:17.983389023Z"
  }
}

Onboarding Webhooks

Onboarding completed

Customer onboarding has been successfully completed.

Schema

Field	Type	Description
customer_id	uuid	The unique identifier for the customer.
currency	string	ISO currency code for the customer's primary currency.

Example

{
  "type": "onboarding_completed",
  "event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
  "event_version": 0,
  "onboarding_completed": {
    "customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "currency": "AED"
  }
}

Onboarding failed

Customer onboarding process has failed.

Schema

Field	Type	Description
customer_id	uuid	The unique identifier for the customer.
currency	string	ISO currency code for the customer's primary currency.
failure_reason	OnboardingError	The reason why the onboarding process failed.

OnboardingError Schema

Field	Type	Description
msg	string	Human-readable error message describing the failure
code	ErrorCode	Machine-readable error code for categorizing the failure type

ErrorCode Values

Code	Description
missing_document	Required document is missing
missing_currency_data	Customer does not have the currency specific data
no_shareholders	Business customer does not have shareholders
insufficient_majority_ownership	Insufficient majority ownership percentage
shareholder_not_onboarded	Shareholder is not onboarded to the specified currency
business_registration_date_missing	Business registration date is missing
individual_missing_proof_of_address_document	Individual does not have proof of address document
business_missing_proof_of_address_document	Business does not have proof of address document

Example

{
  "type": "onboarding_failed",
  "event_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
  "event_version": 0,
  "onboarding_failed": {
    "customer_id": "018c35aa-4279-83e7-a90f-4b2901246c51",
    "currency": "AED",
    "failure_reason": {
      "msg": "Individual `018c35aa-4279-83e7-a90f-4b2901246c51` does not have document `passport`",
      "code": "missing_document"
    }
  }
}