Webhooks - States

dFakto States Machine allows you to create webhooks in order to get notified in case some events happen.

You will need to fill a “Webhook URL” and define which events are interesting for you.

A webhook URL is provided by the receiving application (e.g., check here how to generate one)

The event is sent to the webhook URL in either JSON or XML format.

To manage the webhooks, click on the menu “Webhooks”. The list of the existing webhooks will be displayed.

Create a webhook

To create a new webhook, click on the “Create a webhook” button top right, and the following tab will appear:

You will need to provide the following information:

• Name: it is the name you want to give to this webhook. Choose something easy, that will remind you why you created that webhook.

• Webhook URL: you can find the Webhook URL in the receiving application (e.g., check here how to generate one)

• Events that trigger the notification: you will need to select among different events that will trigger a notification to the webhook URL. Choose wisely, as you could be spammed in case you select too many events. Currently, you can select among (one or more selections are possible):

  • An Execution started

  • An Execution ended

  • A State Machine is created

  • A State Machine is updated

  • A State Machine is deleted

• Additional filters: based on the events you have selected, you now have the possibility to reduce the notifications you may receive, by adding some filters (e.g., by defining only which state machines need). Concretely:

  • If you select the events “An Execution started/ended”, you can add a filter “State machines” to say which States Machines are particularly interesting for you

    • You will not get notified of the other States Machines

  • If you select the event “An Execution ended”, you can add a filter “Execution Status” to say which execution status is relevant (Succeeded, Failed, TimedOut, Aborted)

    • You will not get notified of the other execution status

Once this is done, do not forget to click on the “Save changes” button.

The created webhook will appear in the webhook list view, and it will be “enabled” automatically.

If the webhook fails more than 3 times, the webhook will be automatically disabled.

Modify a webhook

In the list of webhook, find the webhook that you want to modify:

• If you wish to enable/disable it, directly click on the “Enabled” checkbox.

  • If a webhook fails more than 3 times, the webhook will be automatically disabled.

• If you wish to modify the parameters, click on the corresponding “Open” button.

A tab will appear, and, there, you can update the information.

Once this is done, do not forget to click on the “Save changes” button.

Delete a webhook

Find the webhook you wish to delete.

Then, click on the “Delete” button. The webhook will be immediately deleted.

Please note that the webhook cannot be deleted if it is enabled

Check the logs of a webhook

To check the log of a webhook, open the tab ot the webhook. In a section below its configuration, you will see the log appear

The status will tell you whether the event and webhook have been correctly interfaced.
If you wish to follow the content sent to the URL endpoint, click on the “View” button. A pop-up will appear with the detail of the report sent.

The report always follows the same structure:

{
  "event" : {
    "name" : "Name of the webhook",
    "type" : "Type of the webhook",
    "sent_at" : "Date when the webhook has been send"
  }, 
  "state_machine" : {
    "name" : "Name of the state machine",
    "schedule" :{
      "cron": "cron expression of the schedule of the state machine",
      "timezone" : "timezone of the schedule of the state machine"
    },
    "tags" : {
      "key" : "value"
    },
    "create_date" : "Creation date of the state machine",
    "update_date" : "Last update date of the state machine",
    "url" : "Url of the state machine"
  }, 
  "execution" : {
    "id" : "Id of the execution",
    "url" : "Url of the execution",
    "status" : "Status of the execution",
    "start_time" : "Start time of the execution",
    "end_time" : "End time of the execution",
    "error" : "Name of the error. Ex: dFakto.Worker.UnhandledError",
    "cause" : "Detailed message of the error"
  }
}