Receive an HTTP Webhook in Jinba Flow

Use INPUT_WEBHOOK when an external service sends a request to a published flow. The tool reads the value input as a JSON string describing the request and returns the parsed request in result. See Publish for the published flow URL.

Provide the webhook request value

The JSON value must contain method, url, headers (string values), and body. It may also contain query and params (string values). The optional description input labels the step.

- id: receive_webhook
  tool: INPUT_WEBHOOK
  input:
    - name: value
      value: '{"method":"POST","url":"https://example.com/orders","headers":{"content-type":"application/json"},"body":{"orderId":"123"}}'

In a published flow, supply the request through the published endpoint. For a local check, use the sample value above and inspect result.body.orderId; it should be 123. Downstream steps can read steps.receive_webhook.result.body.

Process the received order

The original guide also showed a webhook feeding a later AI step. Use the parsed body from the input result:

- id: summarize_order
  tool: OPENAI_INVOKE
  needs: [receive_webhook]
  input:
    - name: prompt
      value: "Summarize order {{steps.receive_webhook.result.body.orderId}} for the fulfillment team."

Check that the summary mentions the order ID before connecting a real sender.

Verify the sender’s signature

The webhook endpoint is POST https://<your-flow-host>/api/v2/external/flows/<flow-id>/webhook-run. It runs the published version of the flow, so publish after changing the trigger, and answers 404 when the published version has no INPUT_WEBHOOK step. By default requests are accepted unsigned. To require an HMAC-SHA256 signature, set these entries in the step’s config:

Config	Default	Description
`requireSignature`	`false`	Set to `true` to require a signature on every request
`signatureSecret`	—	The HMAC key, as a literal value. A `{{ secrets.X }}` template is not rendered on this route and is rejected
`signatureHeader`	—	Header that carries the signature (hex digest). When omitted, the first present header among `x-webhook-signature`, `x-hub-signature`, `x-stripe-signature`, `x-shopify-hmac-sha256`, `x-discord-signature`, and `x-slack-signature` is used
`timestampHeader`	—	Header carrying the sender’s Unix timestamp (seconds or milliseconds). When set, the signature must cover `<timestamp>.<raw body>` instead of the raw body, deliveries older than `timestampTolerance` are rejected, and a delivery with the same signature as an earlier one is acknowledged without starting another run
`timestampTolerance`	`300`	Maximum age of a timestamped delivery, in seconds
`allowedContentTypes`	`application/json`, `application/x-www-form-urlencoded`, `text/plain`, `application/xml`, `text/xml`	Content types the endpoint accepts

- id: receive_webhook
  tool: INPUT_WEBHOOK
  config:
    - name: requireSignature
      value: true
    - name: signatureHeader
      value: x-webhook-signature
    - name: signatureSecret
      value: "replace-with-the-shared-secret"
  input:
    - name: description
      value: "Signed webhook from the order system"

A trigger with requireSignature but no usable signatureSecret, or with an invalid security config, refuses every request with 401 instead of running unsigned; so does a request whose signature is missing or does not match.

Diagnose a webhook input failure

If the step returns an InputWebhookTool error, check that value is valid JSON and includes method, url, headers, and body with the required types. The tool’s executor parses the request shape; unless requireSignature is set on the step, do not treat this step alone as proof that the sender is authenticated.

​Provide the webhook request value

​Process the received order

​Verify the sender’s signature

​Diagnose a webhook input failure

Provide the webhook request value

Process the received order

Verify the sender’s signature

Diagnose a webhook input failure