Introduction: Webhooks let your flow talk to external systems (CRMs, Airtable, internal databases, analytics tools) in real time. When a contact reaches a Call Webhook action, RapidPro.app sends the flow context as JSON to your endpoint and can store the JSON response so you can use it in the next steps of the flow.
Connect to a webhook (send context, use JSON response)
If you just need the essentials, follow this quick path:
- Collect the input (save it as a named result)
- Call Webhook (POST) and name the webhook result
- Use returned JSON in messages (test one key first)
- Split on returned values (always keep an Other path)
- Handle Failed exits with a safe fallback and/or internal alert
- Debug using webhook events (payload + response)
This pattern lets you integrate external systems while keeping routing predictable and debuggable.
Step-by-Step Process
- In your flow, ask the contact for the value you need (example: Order number, ID, PID, etc.).
- Add a Wait for Response node.
- Save the response with a clear result name (example:
order_number).
[CAPTURE: Send Message asking for an order number → Wait for Response saving result as “order_number”.]
- Add a new node after your Wait for Response.
- Select Call Webhook from the actions list.
- Set the request method to POST (recommended for sending structured data).
- Paste your webhook endpoint URL.
- Name the webhook result (example:
lookup_webhook).
[CAPTURE: Call Webhook action settings showing POST selected, URL field, and a Result/Name field set to “lookup_webhook”.]
If your external service returns JSON like:
{
"status": "Shipped",
"number": "CU001",
"name": "Ben Haggerty"
}You can reference returned keys later using the webhook variable path. Depending on your environment, you’ll typically access it via an @webhook prefix, for example:
@webhook.json.status@webhook.json.number@webhook.json.name
[CAPTURE: A Send Message node showing a message using webhook variables like “Your status is @webhook.json.status”.]
status) to validate your integration, then expand.
- Add a Split by Expression node after the Call Webhook action.
- Evaluate the returned value (example: status).
- Create categories for expected outcomes (example: shipped, pending, cancelled).
- Send tailored messages per category.
[CAPTURE: Split by Expression evaluating @webhook.json.status with categories “shipped”, “pending”, “cancelled”, plus “Other”.]
The Call Webhook action should include Success and Failed routing.
- Connect Failed to an internal alert action (email/notification/log label) if available.
- Optionally send the contact a friendly message (e.g., “We couldn’t check that right now—please try again later.”).
[CAPTURE: Call Webhook node showing Success → normal flow, Failed → Send Email/Notify team.]
- Go to Flows.
- Open the Webhooks (or “Webhook events”) area in your workspace.
- Review recent events in chronological order.
- Open an event to see:
- The request payload sent
- The response JSON returned (if any)
[CAPTURE: Webhook events list, then an event detail view showing request + JSON response.]
Common Issues & Quick Fixes
My webhook returns data, but my flow can’t use it
Problem: The webhook call succeeds, but variables like @webhook.json.* are empty or missing.
Fix: Confirm your endpoint returns valid JSON, and check webhook events to verify the response body. Start by referencing one simple key (like status) before building complex routing.
The webhook response gets cut off
Problem: The stored webhook result appears truncated.
Fix: Return only the fields you need in the flow (keep JSON compact). If you need large payloads, store them in your external system and return only an ID or summary fields.
Contacts fall into “Other” after the webhook
Problem: Returned values don’t match your expected categories.
Fix: Review webhook events to see the exact returned value (including capitalization). Add explicit categories for known outcomes and keep a safe Other fallback message.