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"
  }
]

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)

"jobs": [
    {
      "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"
    }
]