How to use the "Await Webhook" Step in Flows

The "Await Webhook" step in Flows is used to pause a workflow until it receives a specific event via a webhook. This is useful when you need to wait for an external event or system to trigger the continuation of a workflow, such as receiving a payment confirmation, user input, or a third-party API response.

Step Configuration Overview

When configuring the "Await Webhook" step, you’ll need to complete the following:

You’ll need to provide a resume_key. Read further to learn more about it.

You’ll also need to provide a wait until(fail after) time. This by default is 5mins. Usually doesn’t need any longer for most use cases like waiting for a payment confirmation while ordering food, etc.

Resume Key

The Resume Key is a unique value used to correlate the webhook call with the exact instance of the flow execution that should be resumed.

This key can be dynamically set using variables (e.g., user email, ID, or session token).
You can choose from existing variables in your flow or add a custom one.
The resume key should be more than 10 characters long.

Note: The webhook will not resume the flow unless the correct resume key is provided.

Fail After

This configuration allows you to define a timeout for the webhook to be triggered. If no incoming request with the correct resume key is received within the set time:

The flow will fail.
You can handle this failure using a conditional or fallback path in your flow.

Example:
Set Duration = 5 Minutes to allow a 5-minute window for the webhook to be triggered.

Resuming the Flow via CURL

Here’s a sample curl request to trigger the resume of a paused flow:

Contoh kode

curl --request PATCH \
--url https://api.bird.com/workspaces/87608cb1-4f46-4a7e-8edb-c124e36de599/flows/05073d44-23ea-48d4-84df-0fc0de0ab017/runs \
--header 'Authorization: AccessKey $MY_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"action": "resume",
"resumeKey": "$MY_RESUME_KEY",
"resumeExtraInput": {
"custom_key": "The resumeExtraInput is optional and can accept JSON input"
}
}'

Required Parameters:

Parameter	Description
$MY_TOKEN	Replace with your actual API access token. You could find this in your security settings
$MY_RESUME_KEY	Replace with the resume key provided during flow execution, should be more than 10characters long.
resumeExtraInput	Optional JSON object. You can include additional payload if needed.

Example Use Case

Let’s say you're waiting for a user to complete an identity verification process. You send their info to a 3rd-party service, then pause the flow using "Await Webhook".

Once the verification is complete, the third-party system sends a webhook call using the correct resume key to continue the flow. Optionally, it could also send back verification status or additional metadata in resumeExtraInput.

Contoh kode

{
"action": "resume",
"resumeKey": "$MY_RESUME_KEY",
"resumeExtraInput": {
"payment_type" : "credit card",
"payment_status" : "succesful"
    }
}

Additional Tips

Always secure the resume endpoint using your API Access Key.
Use meaningful resume keys to avoid collisions or incorrect resumptions.

By configuring and using the "Await Webhook" step properly, you can make your workflows more dynamic, interactive, and event-driven.