280 lines
6.6 KiB
Markdown
280 lines
6.6 KiB
Markdown
# n8n Webhook Request Format
|
|
|
|
## How Data is Sent to n8n
|
|
|
|
### Backend Request Format
|
|
|
|
Our backend sends data like this:
|
|
|
|
```javascript
|
|
// URL with query parameters
|
|
const url = 'https://workflows.tech4bizsolutions.com/webhook-test/04e677f5-ec57-4772-bf12-96f2610d4b9c?per_page=100&page=1'
|
|
|
|
// POST body sent directly (not wrapped)
|
|
const body = {
|
|
provider: "zoho",
|
|
service: "crm",
|
|
module: "leads",
|
|
acces_token: "1000.xxxxx",
|
|
instance_url: null
|
|
}
|
|
|
|
// Send to n8n
|
|
axios.post(url, body, {
|
|
headers: { 'Content-Type': 'application/json' }
|
|
})
|
|
```
|
|
|
|
### What n8n Receives
|
|
|
|
n8n automatically structures the incoming data as:
|
|
|
|
```javascript
|
|
{
|
|
body: {
|
|
provider: "zoho",
|
|
service: "crm",
|
|
module: "leads",
|
|
acces_token: "1000.xxxxx",
|
|
instance_url: null
|
|
},
|
|
query: {
|
|
per_page: "100",
|
|
page: "1"
|
|
},
|
|
headers: {
|
|
"content-type": "application/json"
|
|
}
|
|
}
|
|
```
|
|
|
|
### How n8n Workflow Accesses Data
|
|
|
|
#### Provider/Service/Module (for routing)
|
|
```javascript
|
|
$json.body.provider // "zoho" or "salesforce"
|
|
$json.body.service // "crm", "books", "people", "projects"
|
|
$json.body.module // "leads", "contacts", "accounts", etc.
|
|
```
|
|
|
|
#### Access Token (for API calls)
|
|
```javascript
|
|
$json.body.acces_token // "1000.xxxxx" or "00DdN00000ne1xG!..."
|
|
```
|
|
|
|
#### Instance URL (for Salesforce)
|
|
```javascript
|
|
$json.body.instance_url // "https://yourinstance.salesforce.com"
|
|
```
|
|
|
|
#### Query Parameters (for pagination/filters)
|
|
```javascript
|
|
$json.query // Full query object
|
|
$json.query.per_page // "100"
|
|
$json.query.page // "1"
|
|
$json.query.instance_url // Also available here for Salesforce
|
|
```
|
|
|
|
---
|
|
|
|
## Provider-Specific Examples
|
|
|
|
### Zoho Request
|
|
|
|
#### Backend Sends:
|
|
```bash
|
|
POST https://workflows.tech4bizsolutions.com/webhook-test/04e677f5-ec57-4772-bf12-96f2610d4b9c?per_page=200&page=1
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"provider": "zoho",
|
|
"service": "crm",
|
|
"module": "leads",
|
|
"acces_token": "1000.a1b2c3d4e5f6...",
|
|
"instance_url": null
|
|
}
|
|
```
|
|
|
|
#### n8n Workflow Uses:
|
|
```javascript
|
|
// Switch routing
|
|
$json.body.provider // "zoho"
|
|
$json.body.service // "crm"
|
|
$json.body.module // "leads"
|
|
|
|
// HTTP Request to Zoho API
|
|
URL: https://www.zohoapis.com/crm/v2/Leads
|
|
Headers:
|
|
Authorization: Zoho-oauthtoken {{ $json.body.acces_token }}
|
|
Query:
|
|
{{ $json.query.toJsonString() }} // {"per_page":"200","page":"1"}
|
|
```
|
|
|
|
### Salesforce Request
|
|
|
|
#### Backend Sends:
|
|
```bash
|
|
POST https://workflows.tech4bizsolutions.com/webhook-test/04e677f5-ec57-4772-bf12-96f2610d4b9c?instance_url=https%3A%2F%2Fability-computing-5372.my.salesforce.com
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"provider": "salesforce",
|
|
"service": "crm",
|
|
"module": "leads",
|
|
"acces_token": "00DdN00000ne1xG!AQEAQN0M3b...",
|
|
"instance_url": "https://ability-computing-5372.my.salesforce.com"
|
|
}
|
|
```
|
|
|
|
#### n8n Workflow Uses:
|
|
```javascript
|
|
// Switch routing
|
|
$json.body.provider // "salesforce"
|
|
$json.body.service // "crm"
|
|
$json.body.module // "leads"
|
|
|
|
// HTTP Request to Salesforce API
|
|
URL: {{ $json.query.instance_url }}/services/data/v59.0/query/?q=SELECT+Id,FirstName...
|
|
Headers:
|
|
Authorization: Bearer {{ $json.body.acces_token }}
|
|
```
|
|
|
|
---
|
|
|
|
## Testing with cURL
|
|
|
|
### Test Zoho
|
|
```bash
|
|
curl --location 'https://workflows.tech4bizsolutions.com/webhook-test/04e677f5-ec57-4772-bf12-96f2610d4b9c?per_page=100&page=1' \
|
|
--header 'Content-Type: application/json' \
|
|
--data '{
|
|
"provider": "zoho",
|
|
"service": "crm",
|
|
"module": "leads",
|
|
"acces_token": "1000.your_zoho_token_here"
|
|
}'
|
|
```
|
|
|
|
### Test Salesforce
|
|
```bash
|
|
curl --location 'https://workflows.tech4bizsolutions.com/webhook-test/04e677f5-ec57-4772-bf12-96f2610d4b9c?instance_url=https%3A%2F%2Fability-computing-5372.my.salesforce.com' \
|
|
--header 'Content-Type: application/json' \
|
|
--data '{
|
|
"provider": "salesforce",
|
|
"service": "crm",
|
|
"module": "leads",
|
|
"acces_token": "00DdN00000ne1xG!your_sf_token_here"
|
|
}'
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation in Backend
|
|
|
|
### src/integrations/n8n/client.js
|
|
|
|
```javascript
|
|
async callWebhook(payload) {
|
|
// 1. Build URL with query parameters
|
|
const queryParams = new URLSearchParams(payload.query || {}).toString();
|
|
const url = `${this.baseUrl}/${this.webhookPath}/${this.webhookId}${queryParams ? '?' + queryParams : ''}`;
|
|
|
|
// 2. Prepare POST body (sent directly, not wrapped)
|
|
const requestBody = {
|
|
provider: payload.provider,
|
|
service: payload.service,
|
|
module: payload.module,
|
|
acces_token: payload.acces_token,
|
|
instance_url: payload.instance_url || null
|
|
};
|
|
|
|
// 3. Send to n8n
|
|
const response = await axios.post(url, requestBody, {
|
|
headers: { 'Content-Type': 'application/json' }
|
|
});
|
|
|
|
return response.data;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Key Points
|
|
|
|
1. **Direct POST Body**: We send the data object directly, not wrapped in another object
|
|
2. **Query Parameters in URL**: Pagination and other params go in the URL query string
|
|
3. **n8n Auto-wraps**: n8n automatically makes it available as `$json.body` and `$json.query`
|
|
4. **Same Format for All Providers**: Zoho, Salesforce, and others use the same structure
|
|
|
|
---
|
|
|
|
## Debugging
|
|
|
|
### View Raw Request in n8n
|
|
|
|
In your n8n workflow, add a "Set" or "Edit Fields" node right after the webhook to see exactly what you're receiving:
|
|
|
|
```javascript
|
|
// Add this as a Set node to debug
|
|
{
|
|
"received_body": "{{ $json.body }}",
|
|
"received_query": "{{ $json.query }}",
|
|
"provider": "{{ $json.body.provider }}",
|
|
"service": "{{ $json.body.service }}",
|
|
"module": "{{ $json.body.module }}",
|
|
"has_token": "{{ $json.body.acces_token ? 'yes' : 'no' }}"
|
|
}
|
|
```
|
|
|
|
### Backend Logs
|
|
|
|
Check backend logs for:
|
|
```
|
|
Calling n8n webhook: { url: '...', provider: 'zoho', service: 'crm', module: 'leads' }
|
|
Sending to n8n: { url: '...', body: { provider: 'zoho', ... } }
|
|
n8n webhook response received: { provider: 'zoho', status: 200 }
|
|
```
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
### Issue: "$json.body.provider is undefined"
|
|
|
|
**Cause**: Data not being sent in POST body
|
|
|
|
**Solution**: Ensure axios is sending the object directly:
|
|
```javascript
|
|
axios.post(url, requestBody) // ✅ Correct
|
|
// NOT
|
|
axios.post(url, { body: requestBody }) // ❌ Wrong (double wrapping)
|
|
```
|
|
|
|
### Issue: "$json.query is empty"
|
|
|
|
**Cause**: Query parameters not in URL
|
|
|
|
**Solution**: Append query params to URL:
|
|
```javascript
|
|
const queryString = new URLSearchParams(payload.query).toString();
|
|
const url = `${baseUrl}?${queryString}`; // ✅ Correct
|
|
```
|
|
|
|
### Issue: "Invalid token"
|
|
|
|
**Cause**: Token not being passed correctly
|
|
|
|
**Solution**: Verify token is in `$json.body.acces_token`:
|
|
```javascript
|
|
// In n8n HTTP Request node
|
|
Authorization: Zoho-oauthtoken {{ $json.body.acces_token }}
|
|
// or
|
|
Authorization: Bearer {{ $json.body.acces_token }}
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: October 9, 2025
|
|
**Version**: 1.0.0
|
|
|