Categories: Helpers

Type: webhook/v1

Actions

Response to Webhook Request

Name: responseToWebhookRequest

Converts the response to the webhook request.

Properties

Example JSON Structure

{
  "label" : "Response to Webhook Request",
  "name" : "responseToWebhookRequest",
  "parameters" : {
    "responseType" : "",
    "headers" : { },
    "body" : {
      "extension" : "",
      "mimeType" : "",
      "name" : "",
      "url" : ""
    },
    "statusCode" : 1
  },
  "type" : "webhook/v1/responseToWebhookRequest"
}

Output

The output for this action is dynamic and may vary depending on the input parameters. To determine the exact structure of the output, you need to execute the action.

What the Caller Receives

This action sets the HTTP response for the Await Workflow and Respond trigger. With the other Webhook triggers, ByteChef sends the response before the workflow runs, so this action has no effect on the response.

ByteChef sends the response when the workflow run is complete. The table shows the response for each Response Type. For all types except Redirect, the Headers that you configure are added to the response.

Notes for Postman and Bruno

• Binary: Postman and Bruno show images and PDFs as a preview. To save the file, use Save response to file in Postman, or the save option in the Bruno response pane.
• Redirect: Postman and Bruno follow redirects automatically. To see the 302 Found response and its Location header, turn off redirect following in the settings of the request.
• Redirect: The Redirect URL must be a relative path, such as /thank-you, or a URL on the same host as ByteChef. For other URLs, ByteChef returns 400 Bad Request with the body Invalid redirect URL.
• Status Code: The Redirect type always uses 302 Found. The Status Code property has no effect.

Example

A Response to Webhook Request step with these settings:

• Response Type: Raw
• Status Code: 202
• Headers: X-Request-Source = bytechef
• Body: Order received

returns this response:

HTTP/1.1 202 Accepted
Content-Type: text/plain
X-Request-Source: bytechef

Order received

Triggers

Auto Respond with HTTP 200 Status

Name: autoRespondWithHTTP200

The webhook trigger always replies immediately with an HTTP 200 status code in response to any incoming webhook request. This guarantees execution of the webhook trigger, but does not involve any validation of the received request.

Type: STATIC_WEBHOOK

Output

{
  "headers" : { },
  "body" : { },
  "parameters" : { },
  "method" : "POST"
}

JSON Example

{
  "label" : "Auto Respond with HTTP 200 Status",
  "name" : "autoRespondWithHTTP200",
  "type" : "webhook/v1/autoRespondWithHTTP200"
}

Webhook Trigger Execution Modes

Use the static workflow webhook trigger URL for this trigger type. This URL becomes available only after the workflow is published and deployed. Any request sent to this endpoint will immediately receive an HTTP 200 OK response, ensuring the workflow is triggered without validating the incoming request.

Testing with Postman or Bruno

For the URLs, body formats and trigger output, see Testing Webhooks with Postman or Bruno.

Request

Response

ByteChef sends the response before the workflow runs. The response does not show the result of the workflow.

A 200 OK response does not confirm that the workflow ran. To see the result, open Executions in ByteChef.

Validate and Respond

Name: validateAndRespond

Upon receiving a webhook request, it goes through a validation process. Once validated, the webhook trigger responds to the sender with an appropriate HTTP status code.

Type: STATIC_WEBHOOK

Properties

Output

{
  "headers" : { },
  "body" : { },
  "parameters" : { },
  "method" : "POST"
}

JSON Example

{
  "label" : "Validate and Respond",
  "name" : "validateAndRespond",
  "parameters" : {
    "csrfToken" : ""
  },
  "type" : "webhook/v1/validateAndRespond"
}

Webhook Trigger Execution Modes

Use the Static workflow webhook trigger URL for this trigger type. This URL becomes available only after the workflow is published and deployed. Incoming requests are first validated by checking the CSRF token sent in the X-Csrf-Token HTTP header. If validation succeeds, the workflow is executed and the sender receives an HTTP 200 OK response.

Testing with Postman or Bruno

For the URLs, body formats and trigger output, see Testing Webhooks with Postman or Bruno.

Request

Response

ByteChef checks the token, then sends the response. The workflow runs after the response is sent, so the response does not show the result of the workflow.

If you get 400 Bad Request, make sure that:

• The request has an X-Csrf-Token header.
• The value is the same as the CSRF Token property, including uppercase and lowercase letters, with no extra spaces.
• The deployed version of the workflow has the token that you send. If you change the token in the editor, publish and deploy the workflow again.

The test URL checks the token in the same way. A request with a missing or incorrect token returns 400 Bad Request and is not recorded as sample output.

Await Workflow and Respond

Name: awaitWorkflowAndRespond

You have the flexibility to set up your preferred response. After a webhook request is received, the webhook trigger enters a waiting state for the workflow's response.

Type: STATIC_WEBHOOK

Properties

Output

{
  "headers" : { },
  "body" : { },
  "parameters" : { },
  "method" : "POST"
}

JSON Example

{
  "label" : "Await Workflow and Respond",
  "name" : "awaitWorkflowAndRespond",
  "parameters" : {
    "csrfToken" : "",
    "timeout" : 1
  },
  "type" : "webhook/v1/awaitWorkflowAndRespond"
}

Webhook Trigger Execution Modes

Use the Static workflow webhook trigger URL for this trigger type. This URL becomes available only after the workflow is published and deployed. Incoming requests are first validated by checking the CSRF token sent in the X-Csrf-Token HTTP header. After successful validation, the workflow starts executing, and the HTTP response is sent when the workflow run is complete. Add the Webhook/Response to Webhook Request action to the workflow to define the exact response body, status code and headers returned to the sender.

Testing with Postman or Bruno

For the URLs, body formats and trigger output, see Testing Webhooks with Postman or Bruno.

Request

Response

The HTTP connection stays open while the workflow runs. ByteChef sends the response when all steps of the workflow are complete, not when the Response to Webhook Request step runs. Steps after Response to Webhook Request also make the response wait. ByteChef waits at most the Timeout (ms) value, or 5 minutes if it is empty. Values longer than 5 minutes are reduced to 5 minutes.

If the workflow runs more than one Response to Webhook Request step, for example in different branches, the last step that runs sets the response.

The test URL checks the token in the same way: a missing or incorrect token returns 400 Bad Request. It does not wait for the workflow and does not apply Response to Webhook Request, so a request with a correct token returns 200 OK with an empty body. To test the response, use the static workflow webhook trigger URL.

Example

Configure the trigger with the CSRF Token my-secret-token. Add a Response to Webhook Request step with Response Type set to JSON, Status Code set to 201, and this Body:

{
  "received": "${trigger_1.body.orderId}",
  "status": "accepted"
}

Send this request:

curl -i -X POST "https://<your-bytechef-host>/webhooks/<id>" \
  -H "Content-Type: application/json" \
  -H "X-Csrf-Token: my-secret-token" \
  -d '{"orderId": 1001}'

The response is:

HTTP/1.1 201 Created
Content-Type: application/json

{"received":1001,"status":"accepted"}

Additional Instructions

Testing Webhooks with Postman or Bruno

Each Webhook trigger listens on a URL. You can use any HTTP client, such as Postman, Bruno or curl, to send a request to it. This section describes what to send. See the section for each trigger above for the response that you get.

Which URL to Use

The production URL has the form https://<your-bytechef-host>/webhooks/<id>. The test URL has the form https://<your-bytechef-host>/webhooks/<id>/test/environments/<environmentId>. Always copy the URL from ByteChef. Do not build it manually.

HTTP Methods

Headers

• Content-Type: Tells ByteChef how to read the body. Postman and Bruno set it automatically when you select a body type.
• X-Csrf-Token: Required for the Validate and Respond trigger and the Await Workflow and Respond trigger. The value must be the same as the value in the CSRF Token property of the trigger. The value is case-sensitive. The header name is not.
• All other headers are sent to the workflow in the headers output.

Body Formats

The Content-Type header controls how ByteChef reads the body:

An empty JSON or XML body is treated as no body, so body is not included. A JSON or XML body that cannot be parsed returns 400 Bad Request, and the detail field of the response describes the error.

Trigger Output

All three triggers give the same output to the next steps of the workflow:

{
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "X-Csrf-Token": "my-secret-token"
  },
  "parameters": {
    "source": "postman"
  },
  "body": {
    "orderId": 1001,
    "status": "paid"
  }
}

• method: The HTTP method of the request.
• headers: The request headers, with the names spelled as the client sent them. A header with one value is a string. A header with more than one value is a list.
• parameters: The query string parameters. A parameter with one value is a string. A parameter with more than one value is a list.
• body: The request body, in the format that the table above shows.

In the next steps, refer to these fields with expressions such as ${trigger_1.body.orderId} or ${trigger_1.parameters.source}.

Example Request

Configure Postman or Bruno as follows:

1. Set the method to POST.
2. Paste the webhook URL from ByteChef. To add query parameters, append them, for example ?source=postman.
3. On the Headers tab, add X-Csrf-Token if the trigger requires it.
4. On the Body tab, select raw → JSON in Postman or JSON in Bruno, and enter the body:

{
  "orderId": 1001,
  "status": "paid"
}

5. Click Send.

The same request with curl:

curl -i -X POST "https://<your-bytechef-host>/webhooks/<id>?source=postman" \
  -H "Content-Type: application/json" \
  -H "X-Csrf-Token: my-secret-token" \
  -d '{"orderId": 1001, "status": "paid"}'

The -i option shows the response status and headers. Use it to compare the response with the tables for each trigger.