Action Meta

Webhooks

Webhooks are a way that you can trigger an action on a stub from an external system.

There are 2 types of webhooks:

1. Implicit - using the stubref as part of the URL
2. Explicit - using a webhook URL with a uuid that was created from a create webhook task

Implicit Webhooks

Implicit webhooks are set via setting some action meta data on the action to enable it.

Webhook url format: https://webhooks.stubber.com/im/{{stubref}}/{{action_name}}

• {{stubref}} is the stub you want to run an action on.
• {{action_name}} is the name of the action you want to run.

You may use POST or GET methods

If you had a stub with the stubref 2023-09-14-XXXX-V1A5 and you want to execute an action named example_action

The webhook url will be https://webhooks.stubber.com/im/2023-09-14-XXXX-V1A5/example_action

Enabling an implicit webhook

To allow an action to be triggered by a webhook you must configure it in the action_meta

Navigate to Advanced tab and add the following json

You can now execute it using the following http request

        GET /im/{{stubref}}/example_action HTTPS/1.1
Host: webhooks.stubber.com
Content-Type: application/json

      

Result:

Putting data into stub.data.payload

By default data will be placed in stub.data.payload

When using the GET method all query params will be placed into stub.data.payload When using the POST method the request body will be placed into stub.data.payload

        {
  "stub":{
    "data":{
      "payload": {
        // data goes here
      }
    }
  }
}

      

Putting data into stub.data

You can configure your data to go to the root of stub.data using the post_data_on_root parameter in the action_meta configuration

        {
  "stub":{
    "data":{
      // data goes here
    }
  }
}

      

Calling a webhook using the GET method

        GET /im/{{stubref}}/example_action?some=data HTTPS/1.1
Host: webhooks.stubber.com
Content-Type: application/json
Authorization: Bearer token

      

Result

        {
  "stub":{
    "data":{
      "payload": {
        "some": "data"
      }
    }
  }
}

      

Calling a webhook using the POST method

        POST /im/{{stubref}}/example_action HTTPS/1.1
Host: webhooks.stubber.com
Content-Type: application/json
Authorization: Bearer token

{
  "some": "data",
}

      

Result

Getting stub.data in response

Using webhooks and external system can pull data from a stub

The default the response will be:

        {
    "success": true,
    "status": 200,
    "payload": {
      "stubdata":{
        // stub.data
      },
    }
  }
}

      

There are 2 ways to enable this functionality:

1. Via a setting a query parameter (_synchronous=true)

        GET /im/{{stubref}}/example_action?_synchronous=true HTTPS/1.1
Host: webhooks.stubber.com
Content-Type: application/json
Authorization: Bearer token

      

2. Via setting action_meta.webhooks.synchronous.enable to true

        {
  "action_meta": {
    "webhooks": {
      "enable": true,
      "synchronous": {
        "enable": true
      }
    }
  }
}

      

Result

the default response for a synchronous webhook

        {
    "success": true,
    "status": 200,
    "payload": {
      "stubdata":{
        // stub.data
      },
    }
  }
}

      

Custom webhook response

You can override the default response and configure it to be any structure you need

Follow the below steps to configure a custom response:

1. set action_meta.webhooks.synchronous.use_custom_return_data to true
2. configure your response structure in action_meta.webhooks.synchronous.return_data

        {
  "action_meta": {
    "webhooks": {
      "enable": true,
      "synchronous": {
        "enable": true,
        "use_custom_return_data": true,
        "return_data": {
          "example": {
            "json": "~~stub.stubref"
          }
        }
      }
    }
  }
}

      

Webhook response

        {
  "example": {
    "json": "2024-03-01-XXXX-35VK"
  }
}

      

Authentication

Authentication is disabled by default.

You may quickly toggle authentication by setting the action_meta.webhooks.authorization.enable field to true

There are 2 authentication types currently available

1. basic
2. bearer

Basic Authentication

To enable basic authentication configure your action_meta like the json below:

        {
  "action_meta": {
    "webhooks": {
      "enable": true,
      "authorization": {
        "enable": true,
        "type": "Basic",
        "keys": {
          "username": "user",
          "password": "pass"
        }
      }
    }
  }
}

      

Bearer Token Authentication

To enable Bearer authentication configure your action_meta like the json below:

        {
  "action_meta": {
    "webhooks": {
      "enable": true,
      "authorization": {
        "enable": true,
        "type": "Bearer",
        "keys": {
          "token": "custom_token"
        }
      }
    }
  }
}

      

Authentication with interpolation

You can use interpolation to dynamically set the authentication keys

Below is an example for setting the stubref as the username and password

        {
  "action_meta": {
    "webhooks": {
      "enable": true,
      "authorization": {
        "enable": true,
        "type": "Basic",
        "keys": {
          "username": "~~stub.stubref",
          "password": "~~stub.stubref"
        }
      }
    }
  }
}

      

Request with Authorization

Below is an example for making a request with basic authentication

In this example we are using the stubref 2024-06-19-XXXX-ASEQ as the username and password

        GET /im/{{stubref}}/example_action?_synchronous=true HTTPS/1.1
Host: webhooks.stubber.com
Content-Type: application/json
Authorization: Basic MjAyNC0wNi0xOS1YWFhYLUFTRVE6MjAyNC0wNi0xOS1YWFhYLUFTRVE=

      

Default response if Authorization success

        {
  "success": true,
  "status": 200,
  "payload": {
    "stubdata":{
      // stub.data
    },
  }
}

      

Default response if Authorization fail

        {
  "success": false,
  "status": 401,
  "error": {
    "type": "conceptual",
    "message": "invalid_credentials"
  }
}

      

Uploading files with form-data

Only Implicit webhooks support form-data.

Below is an example for uploading files

After a sucessful request your files will be added to the stub as attachments