Webhooks

Configuring a webhook endpoint

A single URL for all webhooks can configured in organisation settings in the Portal.

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

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
version	integer	The webhook schema version
payload	Type representing the event type	Payload of the event

Webhook events

The following section provides payload schemas for the various webook events.

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 a 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.
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.",
    "external_id": "01H2ZZV055MFPM8FD9RCJWM6R0"
  }
}

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.

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 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.
timestamp	ISO8601 date time	The timestamp of when the event took place.

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"
  }
}

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",
  }
}

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 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 executed

The outbound exchange transfer has been completed.

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.

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 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 failed.

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"
  }
}