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 webhook supports the following request types:

    • GET
    • DELETE
    • HEAD

    And the following request types with a payload:

    • POST
    • PUT
    • PATCH.

    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.

    It is also possible to customize the response of the webook by setting the `webhook_response` field in the executions outputs.
    this.set_output("webhook_response", {
    "status": 201,
    "body": "created"
    })

    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.

    CRUD Example

    The following is a simple flow script which implements a rest api for a food store. It shows how to read the path of the endpoint and return a custom body and http status.

    import flow_api
    import json
    def handler(system: flow_api.System, this: flow_api.Execution):
    input = this.get('input_value')
    storage_setting = system.setting("food store")
    try:
    storage_setting.get("value")
    except flow_api.exceptions.ResourceNotFoundError:
    storage_setting.set("value", [
    {
    "name": "apple",
    "price": 1,
    },
    {
    "name": "banana",
    "price": 2,
    },
    ])
    storage_setting.acquire()
    storage = storage_setting.get("value")
    status = None
    body = None
    if input['method'] == 'GET':
    if input['path'] in (''):
    status = 200
    body = storage
    else:
    for item in storage:
    if item["name"] == input["path"]:
    status = 200
    body = item
    break
    elif input["method"] == 'POST':
    name = input["data_json"]["name"]
    price = input["data_json"]["price"]
    item = {
    "name": name,
    "price": price,
    }
    storage += [item]
    storage_setting.set("value", storage)
    body = item
    status = 201
    elif input["method"] == 'DELETE':
    storage = [x for x in storage if x["name"] != input["path"]]
    storage_setting.set("value", storage)
    body = ""
    status = 200
    elif input["method"] == 'PATCH':
    for item in storage:
    if item["name"] == input["path"]:
    item["name"] = input["data_json"].get("name", item["name"])
    item["price"] = input["data_json"].get("price", item["price"])
    storage_setting.set("value", storage)
    body = item
    status = 200
    break
    this.set_output("webhook_response", {
    "status": status,
    "body": json.dumps(body),
    })
    return this.success('all done')
    Example
    List all items in the food store
    curl https://<my-workspace>.cloudomation.com/api/latest/webhook/food/call/?key=<my-webhook-key> -X GET
    [{"name": "banana", "price": 2}, {"name": "apple", "price": 1}]
    Example
    Get the food with name "apple"
    curl https://<my-workspace>.cloudomation.com/api/latest/webhook/food/call/apple?key=<my-webhook-key> -X GET
    {"name": "apple", "price": 1}
    Example
    Delete a food item.
    curl https://<my-workspace>.cloudomation.com/api/latest/webhook/food/call/apple?key=<my-webhook-key> -X DELETE
    Example
    Create a new food item
    curl https://<my-workspace>.cloudomation.com/api/latest/webhook/food/call?key=<my-webhook-key> -X POST -d '{"name": "apple", "price": 2}' -H 'Content-Type: application/json'
    {"name": "apple", "price": 2}
    Example
    Update an existing item
    curl https://<my-workspace>.cloudomation.com/api/latest/webhook/food/call/apple?key=<my-webhook-key> -X PATCH -d '{"price": 1}' -H 'Content-Type: application/json'
    {"name": "apple", "price": 1}

    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
    Vault Integration
    Next — Knowledge Base
    Workspace Linking