Webhook actions let your AI agent call external systems during a conversation.
Almost every webhook action fits one of two use cases:
Read – looking up data
Write – writing data
Designing your setup around these two use cases from the start makes your agent easier to configure, test, and trust.
Before you start
Make sure you have:
Access to the Webhook feature in your plan
A working API endpoint
Authentication details (e.g. API key or bearer token)
A short list of fields your API requires
Then: open your agent → Tools → enable Webhook → Add Action.
Use case 1: Reading data
Use a read action when the agent needs information before it can answer.
Typical scenarios
Check order status
Retrieve customer details
Validate account or booking information
Example: Get order status
Action setup
Field | Value |
Title | Get order status |
Method | GET |
URL |
|
Description | Retrieves the latest shipping and delivery status for a specific order |
When to use | Use when a customer asks where their order is or requests delivery timing |
Content type | none |
Authentication type | header |
Authentication field
Key | Value |
Authorization |
|
Parameter
Name | Location | Type | Required | Example |
orderId | query | string | yes | ORD-10458 |
Request sent by the webhook
GET /v1/orders/status?orderId=ORD-10458 HTTP/1.1
Host: api.demo-shop.com
Authorization: Bearer demo_read_token_123
Example response
{
"orderId": "ORD-10458",
"status": "shipped",
"estimatedDeliveryDate": "2026-09-05",
"carrier": "DHL",
"trackingNumber": "DHL-77890012"
}Use case 2: Writing data
Use a write action when the agent should create, update, or close data in another system.
Typical scenarios
Create a support ticket
Update customer contact details
Cancel or reschedule an appointment
Example: Create support ticket
Action setup
Field | Value |
Title | Create support ticket |
Method | POST |
URL |
|
Description | Creates a new support ticket in the helpdesk system |
When to use | Use when the customer reports an issue that cannot be resolved immediately and agrees to open a ticket |
Content type | application/json |
Authentication type | header |
Authentication field
Key | Value |
Authorization |
|
Parameters
Name | Location | Type | Required | Example |
ticket.subject | body | string | yes | Billing issue for invoice INV-983 |
ticket.description | body | string | yes | Customer says invoice amount is incorrect and requests review. |
customer.email | body | string | no |
Request sent by the webhook
POST /v1/tickets HTTP/1.1
Host: api.demo-helpdesk.com
Authorization: Bearer demo_write_token_456
Content-Type: application/json
{
"ticket": {
"subject": "Billing issue for invoice INV-983",
"description": "Customer says invoice amount is incorrect and requests review."
},
"customer": {
"email": "[email protected]"
}
}
Example response
{
"ticketId": "TCK-22091",
"status": "open",
"priority": "normal",
"createdAt": "2026-09-02T10:14:22Z"
}One action per job
Don't combine read and write behavior in a single action unless your API requires it.
Best practice: one action to look up data, a separate action to write data. This reduces mistakes and makes behavior easier to audit.
Field guide
Applies to both read and write actions.
Action fields
Field | Purpose |
Title | Human-friendly name |
HTTP Method | GET, POST, PUT, PATCH, or DELETE |
URL | Full URL, including |
Description | What the action does |
When to use | Exactly when the agent should choose this action |
Tip: Title, Description, and When to use are the strongest signals the agent uses to pick the right action — invest time here.
Parameters
Add one parameter for every value your endpoint expects.
Field | Notes |
Name | Field key to send. Supports dot notation for nested values, e.g. |
Location | query, header, or body |
Type | string, number, boolean, enum, or array |
Required | Enable for mandatory fields |
Description | Explain the expected value |
Example | Optional, but helps extraction accuracy |
Type-specific rules
Type | Rule |
String | Optional min/max length |
Number | Optional min/max value, with decimal toggle |
Enum | Must include at least one allowed value |
Array | Item type must be string, number, or boolean |
Content type
Choose one:
application/json— if your endpoint expects JSONapplication/x-www-form-urlencodednone
Authentication
Choose where auth fields are sent: none, header, body, or query.
If auth type is header, body, or query, add at least one key/value pair, for example:
Key | Value |
Authorization |
|
Troubleshooting save errors
If saving an action fails, check for these issues, grouped by area:
Action-level
Missing title
Invalid method (must be GET, POST, PUT, PATCH, or DELETE)
Invalid URL (must be a full URL)
Duplicate action name
Authentication
Authentication fields missing a key or value
Parameters
Invalid parameter location (must be query, header, or body)
Invalid parameter type
Enum parameter without values
Duplicate parameter name in the same location
Invalid min/max constraints (minimum cannot exceed maximum)
Security and reliability
Use separate credentials for test and production
Grant least-privilege API permissions
Always use HTTPS endpoints, never plain HTTP
Prefer header auth over query auth when possible
Avoid sensitive values in parameter examples
Make write endpoints idempotent where possible
Return clear API errors from your external system
Verifying the caller before sharing sensitive data
Never release sensitive information based on Caller ID alone. Caller ID is easily spoofed and should not be treated as proof of identity.
Instead, require the same kind of verification a human agent would use before disclosing account details, for example:
Last digits of the customer or account number
Date of birth
Postal code
Other knowledge-based details only the real customer would know
Build this check into the action itself: make the verification fields required parameters, and set the "When to use" guidance so the agent asks for and confirms this information before it calls any action that returns sensitive data.