Service Block Type: Custom API Request (Webhooks)

Dodgeball offers the ability to leverage custom API requests to interact with other systems during a checkpoint workflow. These offer essentially unlimited extensibility of workflow functionality and can interact with any system that has an API.

What is a webhook

A webhook is an automated way to call an API

What is an API

An API is a very standard method of communication between systems using web requests

How do I know how to set up a webhook in Dodgeball?

The best way to set up a webhook in Dodgeball is to know exactly what web request you want Dodgeball to make, where to interpolate data, and then fill out the relevant fields on the Service Block.

How do I know what web request to make?

Reference documentation to see what structure is expected. This documentation should be provided by clients.

Use a standard tool like Postman to test out some web requests until things are working.

Check out this video for a simple introduction to Postman and how to use it to call an API:

https://www.youtube.com/embed/MFxk5BZulVU?showinfo=0

What about safely handling secrets?

Clients should never enter secrets like API keys directly into Service Block Parameters like Webhook configuration.

Check Checkpoints and Integrations to see how to safely handle secrets for webhooks. This will likely be required for webhooks, because many require authentication.

Real-world example: Calling ChatGPT API

Let’s imagine that a customer wants to call ChatGPT and provides us with the following documentation: https://platform.openai.com/docs/api-reference/chat/create

Figuring out what to send

In that documentation, we can see that we have to make a POST request to https://api.openai.com/v1/chat/completions

If we ignore everything else in the docs and just send that request in Postman, we get an error message saying we need to provide an API key.

I have already set up my API key via secrets, but I will do the same for Postman.

Now the error message has changed to you must provide a model parameter

Looking at the docs, we need to provide a model, and some messages to start the chat. Lets try this payload under the Raw JSON body:

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a famous poet who admires ee cummings."
      },
      {
        "role": "user",
        "content": "Can you write me a short poem about webhooks?"
      }
    ]
}

Now we get a response that we want based on the prompt!

Now that our request is validated and working, we can use the config to set up a webhook in Dodgeball.

Configuring the Webhook in Dodgeball

The “Custom API Request” Service block lives under the “Advanced” tab on the step palette.

This screenshot shows how to provide the following:

1. Description (used to label the step in the Checkpoint Studio)
2. Method (Known via Docs. Tested in Postman)
3. URL (Known via Docs. Tested in Postman)
4. Customer Headers Template — This was tested in Postman, but the name of the secret to interpolate is slightly different, and based on this Checkpoints and Integrations - Note that this example also adds a Content-Type header: this is not strictly required for the OpenAI example. Clients should tell you which headers they want to use.

Data Template - this is slightly adjusted from the example we tested. Instead of predefining the message to send to ChatGPT, we are actually taking it from Checkpoint Event data and interpolating via {{event.aiCommand}} - fun!

1. Response Data Format - This defines how we should parse responses. JSON is very standard. If clients need to parse a different type of response, we would need to add that functionality.
2. Output Data Mapping - Clicking this opens up a modal that lets you manage the output data mapping. See Checkpoints and Integrations for information about how this mapping works
3. Enable or Disable Caching - This is an option that lets repeated requests immediately return previous results. There are pros and cons to enabling caching. Leave it off unless a client requests to turn it on.
4. Advanced Options - You can configure things like failure handling, timeouts, and default data in Advanced Options. It is a best practice to set these fallbacks and return default data, but clients should make this determination.

Testing the webhook

When you have a checkpoint with a webhook, you can test it by running the checkpoint and viewing developer logs, which have augmented logging for Webhook Service Blocks.

Here is an example for the webhook configured above: