Skip to Content

Webhooks in Jitterbit App Builder

Overview

A webhook is an automated notification sent between applications when a specific event occurs. App Builder uses Webhooks to trigger specific actions in response to emails, text messages, or API calls.

For example, an application might email a user to approve or reject a transfer. If the user replies "approve", a webhook triggers the approval process; if they reply "reject", it triggers a rejection. This allows users to complete tasks directly from their inbox or messaging app without having to log back into the main application.

Create a webhook

Here is a summary of the steps needed to create a webhook:

Step 1: Add webhook in data servers

To set up a server, follow these steps:

  1. Navigate to the IDE.

  2. Select IDE > Data Servers.

  3. Click + Server. The Server dialog opens:

    server dialog

    1. Set values for the following:

      • Server Name: Enter a name.

      • Type: Select Webhook API. This causes more options to be shown.

      • Request Content Type: Select JSON.

      • Response Content Type: Select JSON.

    2. Click Save.

    3. Exit the dialog.

To create an endpoint, follow these steps:

  1. In the list of servers, find the server you've just created and select it. Doing so lists the new server in the other panel on the screen.

  2. Click the Open record icon:

    open record

  3. The Webhook API popup opens. In the REST API section, click Endpoints:

    webhook api popup

  4. The Web Service page opens. In the Endpoints panel, click + Endpoint:

    web service page

    Set values for the following parameters:

    • Name: Pick a name for your endpoint.

    • Endpoint: You can leave this field empty.

    • Method: Select POST.

  5. Click the checkmark icon to save.

To create parameters for your endpoint, follow these steps:

  1. In the Endpoints panel, click Discover. The Endpoint dialog opens:

    endpoint dialog

    1. Set values for the following:

      • Name: This field is automatically filled with the name you've chosen for the endpoint.

      • End Point: You can leave this field empty.

      • Method: Select POST.

      • Request Body: If the webhook accepts a body (e.g., a POST using JSON or XML Request content type), provide a sample request body. For example:

        {
    "Company": "Jitterbit",
    "Product": "App Builder"
}

    2. Click Discover. App Builder automatically adds the endpoint parameters.

Step 2: Add webhook to your application

To add the webhook to your application, follow these steps:

  1. Go to App Workbench > Data Sources.

  2. Click + Source. A dialog opens.

  3. Select Link to existing source.

  4. Click Next.

  5. Locate and select the REST Webhook API that you configured in Step 1 in the list.

  6. Click the Link button.

  7. Click Done.

Step 3: Create a webhook business rule

To create a business rule, follow these steps:

  1. Go to App Workbench > Data Sources.

  2. In the App Data Sources panel, select the webhook data source you've just created:

    create a rule

  3. In the Rules panel, click + Rule. The Rule Builder opens.

  4. Configure your new rule as follows:

    • Name: Enter a descriptive name for the rule, for example, WebhookCreation.

    • Purpose: Select Webhook. Doing so causes more options to appear.

    • Source Data Source: Select the webhook data source from Step 1.

    • Target: Select the webhook endpoint from Step 1.

  5. Click Create. App Builder creates the rule and shows its edit screen.

  6. In the Tables panel, click + Tables. A dialog opens.

  7. Select the webhook endpoint by clicking its Add button. It appears on the Tables panel.

  8. In the Tables panel, select all columns from the endpoint.

Step 4: Create an XP CRUD business rule

To create an XP CRUD business rule, follow these steps:

  1. In the edit screen of the business rule you've created in Step 3, click Events in the Rule panel. The All Events dialog opens.

  2. Double click the row with the Insert event. The Insert window opens:

    insert window

  3. In the Event Information panel, select Row Refresh in the Refresh Scope menu.

  4. In the Actions panel, click + Rule & Register. A new instance of the Rule Builder opens. Configure it as follows:

    • Name: Give it a descriptive name, for example, WebhookCreation_XP_CRUD.

    • Purpose: Select XP CRUD.

    • Action: Select Insert.

    • Target Layer: Select Logic Layer.

    • Target: Select the business rule you created in Step 3.

  5. Click Create. The new business rule is created and its edit screen appears.

  6. In the Tables panel, click + Tables.

  7. Select the endpoint you created in Step 1 by clicking its Add button. It will be shown on the Tables panel.

  8. Select all of its columns.

  9. Click Validate.

Step 5: Expose webhook

To create an endpoint for your application, follow these steps:

  1. Select IDE > REST APIs.

  2. Go to the Webhooks tab.

  3. In the Application panel, click the Manage Endpoints button to open the Application Endpoints dialog:

    manage endpoints

  4. Locate your application and click its pencil icon.

  5. Enter a name for your endpoint, then click Proceed.

  6. Exit the dialog. Your application will be listed with the others in the Application panel. Click its tile once to select it.

  7. In the Webhooks panel, click + Webhook. The Webhook dialog opens:

    webhook dialog

    Configure it as follows:

    • Webhook: Select the webhook you've created.

    • Endpoint: Enter a descriptive name.

    • Compatibility: Leave the default option.

      Note

      Since App Builder 4.51, the Compatibility field provides these options:

      • Version 1: Use the original REST behavior—Insert events are not preceded by New events. (Default for endpoints created with App Builder 4.50 and earlier.)

      • Version 2: Use an improved REST behavior—New events and any default rules are invoked before Insert events. (Default for endpoints created with App Builder 4.51.)

      • Version 3: (Since App Builder 4.52.) Same as version 2, but where APIs return the logical value instead of the storage value. For example, boolean values are returned as true or false instead of 1 or 0. (Default for endpoints created with App Builder 4.52 and later.)

  8. Click Save.

Step 6: Create an API key for a user to access this webhook

To create an API key (to allow a user access this webhook), follow these steps:

  1. Select IDE > User Management.

  2. In the Users panel, select a user that has administrator privileges and double click their row. The User dialog opens:

    user dialog

  3. Click More > Keys. The Keys dialog opens.

  4. Click Create. The Generate Key dialog opens.

  5. Configure the new key as follows:

    • Provider: Select APIKey.

    • Description: (Optional) Provide a brief description.

    • Expires In: (Optional) Enter a custom expiration time.

  6. Click Save to create the API key.

Important

Note down the information as it cannot be shown again.

user dialog

Step 7: Test

You should test your new webhook (using, for example, Postman, Insomnia, or similar tools). Send a POST API call with a body similar to the body sample used to create the parameters in Step 1. You should use basic authentication with the identifier and the key from Step 6 as the username and password.

For testing, use the link: https://<url>/webhook/v1/<application-endpoint>/<endpoint>.

When no authentication is required, instead of configuring an x-api-key in the header, you can adjust the URL to one of the following options:

  1. https://{{user's identifier from Step 6}}:{{user's key from Step 6}}@{{url from Step 7}} (to be used if the provider is HTTP basic auth with no parameters)

    Caution

    The HTTP basic method described above requires the Authorization header to be included in the received payload. To bypass this, use the API Key method instead.

  2. https://{{url from step7}}?apiKey={{user's key from Step 6}} (to be used if the provider is API Key and the Properties include HttpHeaderName 'X-API-Key')