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:

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