Webhook Interfaces

Overview

You can provide optional additional meta information for your webhook which can be used to render a user interface. This is done with the InterfaceManager which is created via the getInterfaceManager method. When constructed, a new route will become available which will describe the acceptable fields and the types of data the webhook expects.

var im = webhook.getInterfaceManager();
// => GET /hooks-ui/proof/create

The global /hooks route will now display an additional parameter interface_path for webhooks with a registered interface.

GET http://localhost:8081/hooks

[
  {
    "id": "HkOmpOgC",
    "path": "/hooks/proof/create",
    "nest": "proof,create",
    "tunnel": "Webhook tunnel test",
    "method": "get",
    "interface_path": "/hooks-ui/proof/create"
  }
]

Sessions

Webhook interfaces will have an auto-generated session ID. This session ID is used to keep track of the progress of step events while making requests to the UI. If you make a request to the UI without providing a valid active session ID, a new UI session is created.

Sessions can be specified via the querystring or form data values:

// GET http://localhost:8081/hooks-ui/test/example?sessionId=H1fC0c2RA
{
  "sessionId": "H1fC0c2RA",
  "fields": [],
  "heldJobs": [
    {
      "id": "B17FWOhCA",
      "name": "test.txt",
      "path": "./example/automanaged/test/checkpoint/test.txt"
    }
  ],
  "steps": [],
  "metadata": {
    "interfaceProperties": []
  }
}

Interface instances

The interface manager which is used to add steps and fields within your workflow is decoupled from the actual interface instance. This is so you can manipulate the interface instance (which is tied to a session) depending on the initial behavior.

Interface instances are only available through the callback of some methods like addStep:

var im = webhook.interfaceManager;
im.addStep("Check job number", function(webhookJob, webhookInterface, step, done) {
    // webhookInterface is an interface instance...
});

Fields

Fields are constructed with the addField method and take a FieldOptions object in its constructor.

im.addField({
    id: "job_number",
    name: "Job Number",
    type: "text"
});
im.addField({
    id: "action",
    type: "select",
    name: "Action",
    acceptableValues: ["Append proof", "Submit new proof"],
    required: true
});
im.addField({
    id: "csr_email",
    placeholder: "[email protected]",
    name: "CSR Email",
    type: "text"
});

Visiting the interface route for this webhook (via GET) displays all of the field information.

GET http://localhost:8081/hooks-ui/proof/create

{
  "fields": [
    {
      "id": "job_number",
      "name": "Job Number",
      "type": "text"
    },
    {
      "id": "action",
      "type": "select",
      "name": "Action",
      "acceptableValues": [
        "Append proof",
        "Submit new proof"
      ],
      "required": true
    },
    {
      "id": "csr_email",
      "placeholder": "[email protected]",
      "name": "CSR Email"
    }
  ]
}

Here is an example of how antfarm-ui displays this information:

Steps

Steps allow you to control or change your UI based on request parameters sent to the webhook interface itself. You can use this to validate or check field values and then add more fields to the interface. In the example below, we use the method getField to get the field from the interface instance and modify its properties, making it read only.

When the step is completed, you should call the completeStep method which will remove it from the interface. In antfarm-ui, the submit button is not displayed if any steps remain.

im.addStep("Check job number", function(webhookJob, webhookInterface, step, done) {

    if(webhookJob.getParameter("job_number").length == 6) {

        // Make job number read only
        var jobNumberField = webhookInterface.getField("job_number");
        jobNumberField.readonly = true;

        webhookInterface.addField({
            id: "file",
            name: "File",
            type: "file",
            tooltip: "Here is a tooltip"
        });

        webhookInterface.completeStep(step);

    } else {
        step.failure = "Job number was not 6 characters.";
    }
    done();
});

Checkpoints

Webhook interfaces can also be tied to nests via the checkNest method. This allows the interface to see pending jobs within a nest, allowing users to make decisions about how they should be processed.

var pending = af.createAutoFolderNest("outfolder");
ui.checkNest(pending);

The interface will now have a array of pending jobs that are waiting in the nest. GET http://localhost:8081/hooks-ui/proof/create (excerpt)

"heldJobs": [
    {
      "id": "rkUmCYeC",
      "name": "hello copy 5art.pdf",
      "path": "./example/automanaged/outfolder/hello copy 5art.pdf"
    },
    {
      "id": "B1xU7RFxA",
      "name": "hello copyart.pdf",
      "path": "./example/automanaged/outfolder/hello copyart.pdf"
    }
]

You can then access these held jobs with the getHeldJob method on the nest with the held job. For example:

var tunnel = af.createTunnel("Checkpoint example");
var webhook = af.createWebhookNest(["test", "example"], "get");
var holding_folder = af.createAutoFolderNest(["test", "checkpoint"]);

var im = webhook.interfaceManager;

// Watch for jobs, hold, and provide to the interface.
im.checkNest(holding_folder);

tunnel.watch(webhook);

tunnel.run(function(job, nest){
    // Get the job_id from the webhook request
    var job_id = job.getParameter("job_id");
    // Get the held job from the holding folder
    var checkpoint_job = holding_folder.getHeldJob(job_id);
    // Move somewhere else
    checkpoint_job.move(af.createAutoFolderNest(["test", "outfolder"]));
});