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.

This page teaches you the steps to create and configure a webhook:

This page also contains a Troubleshooting section addressing a common webhook error and how to resolve it.

Create a webhook

Follow these steps to set up and expose a webhook end to end:

Step 1: Add a webhook data server

A webhook needs its own data server, of type Webhook API, to receive incoming HTTP calls. Follow these steps to create one:

  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.

With the server created, define the specific endpoint the webhook will call:

  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 dialog opens. In the REST API section, click Endpoints:

    webhook API dialog

  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.

Finally, discover the parameters the webhook's request body will provide:

  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 the webhook to your application

With the webhook server and endpoint defined, link that server into your application as a data source:

  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

Next, create a business rule that maps the webhook's incoming data to a usable data source:

  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

The webhook rule alone only defines the shape of the incoming data. Attach an XP CRUD rule to its Insert event so that data becomes available to other rules and tables in your application:

  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 the webhook

Finally, expose the webhook rule through App Builder's REST API, so external systems can call it over HTTP:

  1. Select IDE > REST APIs.

  2. Go to the Webhooks tab.

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

    Applications dialog

  4. Locate your application and click its pencil icon.

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

  6. (Since App Builder 4.67.) Click the Authentication icon for the application. The Authentication Providers dialog opens. Add the API key, HTTP, or Authorization Server providers you want to allow to authenticate this application's Webhook requests. See Configure an endpoint for the exact steps.

  7. Exit the dialog. In the Services panel, click the chevron icon on your application's tile. The Webhook API page opens, showing the Service and Webhooks panels.

  8. (Since App Builder 4.67.) In the Service panel, click More > Configure Authentication:

    More menu, Configure Authentication button

    The same Authentication Providers dialog from step 6 opens. Add and save providers the same way described there.

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

    Webhook dialog

    Configure it as follows:

    • Webhook: Select the webhook rule you've created. Once the dialog is saved, the icon next to this field becomes clickable, taking you to the rule's Rule Builder page in the App Workbench.

    • Endpoint: Enter the path segment where the webhook is accessed.

    • Compatibility: Leave the default option. See Compatibility for the available options, which apply here too.

  10. Click Save.

  11. (Optional.) Click the webhook's details icon to see the Webhook dialog, where you can configure request/response plugins that transform the payload as it passes through the webhook.

Step 6: Create an API key for a user

Finally, generate an API key so a specific user can authenticate calls to this webhook:

  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 your API Key security provider (see Set up a security provider API key if you haven't configured one).

    • 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 the webhook

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')

Troubleshooting

For a common cause of webhook authentication failures, see Webhook: HTTP Basic Auth requires the Authorization header in the payload in the App Builder troubleshooting guide.