Webhooks

Webhooks are notifications about significant events occuring in the system in the context of a customer account, sent as a JSON encoded payload over HTTPS to an endpoint of the customer's choosing.

A typical webhook notification consists of one or more events and has the following structure:

[
  {
    "EntityType": "{entityType}",
    "EntityId": {entityId},
    "Reason": "{eventName}",
    "ApiUrl": "{entityUrl}"
  }
]

parameter	description	details
entityType	the type of entity the event relates to	either "Deposit", "Withdrawal", "Transfer", "Instruction" or "Account"
entityId	the unique identifier of the entity the event relates to	integer
eventName	the name of the event that has occured on the entity	details available in the documentation for the specific entity
entityUrl	the freemarket API URL that identifies the entity	further details about the entity can be retrieved from this URL

A typical webhook notification workflow from the integrators point of view would be

• listening to incoming webhooks on an HTTPS endpoint
• parsing of the individual notifications from the message
• per every notification
  • make a decision based on the EntityType and EventName to either process or ignore the webhook (not all webhook notifications are relevant to every integrator, they will however be sent regardless)
  • retrieve details about the entity using the ApiUrl and execute a workflow in the integrating software to handle the event

Webhook delivery retry policy

In order to try and guarantee delivery of the webhook notifications, a retry policy is in place that retries the delivery until a response with a success status code (2xx) is received. The specific configuration of the retry policy is subject to change, but generally there is a number of retries in short succession to try and work around possible transient issues with the network connection, and another number of retries at a later time to try and work around possible issues with the webhook recipient itself (e. g. server restarts, virtual IP swaps, etc). If all of these fail, the problem is raised with an operator.

Note

Due to the presence of this retry policy and the unreliability of distributed systems and their components, it is possible to receive a webhook notification multiple times. Every event for a unique entity instance can only occur once in the system however.