Close
    logoCloudomation Docs

    Webhooks

    The webhooks resource type allows you to configure a webhook with Cloudomation that triggers a specific flow script. Creating this resource configures an endpoint at https://<my-workspace-name>.cloudomation.com/api/latest/webhook/<my-webhook-name>/call. A GET or POST request to that URL will execute a flow script. Optionally, the webhook can return a response.

    A HTTP GET request should only be used to retrieve a resource, while a HTTP POST request should be used to create a resource. Triggering a Cloudomation webhook creates an execution. Thus the recommended way to trigger a webhook is by using a POST request. For compatibility reasons Cloudomation also allows triggering webhooks using a GET request.

    To register a webhook, you can simply select the flow script (either in the flow list view via the checkbox or open the flow script by clicking on its name) and hit the button ‘Create webhook’.

    This will lead you to the details view of the new webhook resource:

    You can change the name and other fields by clicking on it. We recommend short, significant names and to avoid spaces in the name. The key field is optional. If specified, the request must contain the key in the query string or JSON payload.

    The flow will receive a dictionary containing the request headers and payload.

    The standard behavior of the webhook is to execute the flow script and wait for the flow script to finish (synchronous execution). To execute the flow scrit asynchronously, add the parameter async=1 to the webhook call, which will trigger the flow script and return a HTTP code immediately without waiting for the flow script to finish.

    You have to enable a webhook in order to use it. It is disabled after creation by default. To do this click on the x-icon next to ‘Is enabled’. It will change to a checkmark and you will see a short notification that the webhook is now enabled and ready to use.

    Response

    The webhook will return the following response, depending on whether you specify a key or not, and whether you execute the flow script synchronously or asynchronously by specifying the async parameter:

    key=NONE (or is not set) and async=0 (or not set): HTTP 200 or HTTP 500 depending on whether or not the flow ended with success, and a json response with status: status message

    key=NONE (or is not set) and async=1 (or not set): HTTP 200 and no json response.

    key="my-super-secret-key-nbody-else-knows" and async=0 (or not set): HTTP 200 independent of whether or not the flow script ended with success, and a json response containing the entire execution record including the ended status and status message.

    key="my-super-secret-key-nbody-else-knows" and async=1 (or not set): HTTP 200 and a json response containing the execution record at the moment the flow script was started, which contains the current status (most likely “running”) and the execution ID as well as all other fields of the execution record.

    Example Calls

    Example
    curl -d '{"key": "my-super-secret-key-nobody-else-knows"}' https://my-workspace-name.cloudomation.com/api/latest/webhook/update_dns_subdomain/call?key=my-super-secret-key-nobody-else-knows

    The above call will trigger the flow script, wait for it to finish and return the flow script itself as well as its inputs and outputs as a JSON response.

    Example
    curl -d '{"key": "my-super-secret-key-nobody-else-knows"}' https://my-workspace-name.cloudomation.com/api/latest/webhook/update_dns_subdomain/call?key=my-super-secret-key-nobody-else-knows&async=1

    The above call will trigger the flow script and return immediately without waiting for the flow to finish. The JSON response will contain the execution id.

    Webhooks in Development Mode

    Executions can also be started in development mode via a webhook. To configure a webhook to start executions in development mode, simply uncheck ‘Is productive’ in the webhook resource detail view by clicking on the checkmark-icon next to ‘Is productive’. It will change to a x-icon. Unless you specify otherwise, executions will be executed in productive mode by default.

    Make sure you enable ‘Is productive’ again for your webhooks when finished with development! Otherwise the executions will not run.

    Find more information about the development mode on the page Development and Productive Mode.

    Summary

    Creating a webhook from a flow with the name “update_dns_subdomain” will create a webhook at the endpoint https://my-workspace-name.cloudomation.com/api/latest/webhook/update_dns_subdomain/call. You need to enable the webhook before it can be used.  A GET or POST request to that URL will execute the flow named update dns subdomain with the permissions of the user who created the webhook. Optionally, you can specify a key for the webhook.

    Knowledge Base — Previous
    Using Python Functionality in Flow Scripts
    Next — Knowledge Base
    Exceptions