Skip to main content

​
Overview

The Webhook automation type sends HTTP POST requests to external URLs when automation events are triggered. This enables real-time integration with external systems, allowing you to extend MileApp’s functionality and connect with third-party applications, custom dashboards, or enterprise systems. Webhooks are the most versatile automation type, available for all automation events, making them ideal for system integrations and custom workflows.
Webhook automation configuration

Webhook automation configuration showing URL and custom headers

​
When to Use Webhook

Use this automation type when you need to:
  • Integrate MileApp with external systems (ERP, CRM, custom applications)
  • Send real-time notifications to external dashboards or monitoring systems
  • Trigger custom workflows in third-party platforms
  • Synchronize data with external databases or services
  • Build custom automation logic that extends beyond MileApp’s built-in capabilities

​
Event Availability

Webhook automation type is available for ALL events:
  • On Task Created - Send webhook when a task is created
  • On Task Assigned - Send webhook when a task is assigned
  • On Task Finished - Send webhook when a task is completed
  • On Data Source Created - Send webhook when new data is added to Data Source
  • On Routing Finished - Send webhook when route optimization completes
  • On Routing Dispatched - Send webhook when routes are dispatched
  • On Start Trip - Send webhook when a trip starts
  • On Finish Trip - Send webhook when a trip finishes

​
Configuration Fields

When you select Webhook as the automation type, you need to configure the following:

​
1. URL *

The destination endpoint URL where the webhook POST request will be sent. Requirements:
  • Must be a valid HTTPS URL (recommended for security)
  • Should be a publicly accessible endpoint
  • Must be able to receive HTTP POST requests
Example URLs: 
https://api.example.com/webhooks/delivery
https://your-domain.com/api/mileapp/webhook
https://hooks.slack.com/services/YOUR/WEBHOOK/URL

​
2. Header and Value (Optional)

Custom HTTP headers to include in the webhook request. You can add multiple headers as needed. Common Use Cases:
  • Authorization: Authentication tokens or API keys
  • Content-Type: Specify request content type (usually application/json)
  • Custom Headers: Any custom headers required by your endpoint
Example Headers:
HeaderValuePurpose
AuthorizationBearer your-api-token-hereAPI authentication
Content-Typeapplication/jsonSpecify JSON payload
X-Custom-Headercustom-valueCustom application headers
X-API-Keyyour-api-keyAlternative authentication method
Adding Headers:
  1. Enter header name in the “Header” field
  2. Enter header value in the “Value” field
  3. Click “Add Header” to add additional headers
  4. Click the trash icon to remove headers

​
Webhook Payload

When the webhook is triggered, MileApp sends a POST request with a JSON payload containing event data.

​
Payload Structure

The webhook payload contains complete information about the triggered event: For Task Events (On Task Created, On Task Assigned, On Task Finished): 
{
  "_id": "task_id_here",
  "flow": "Delivery",
  "flowId": "flow_id_here",
  "status": "DONE",
  "hubId": "hub_id_here",
  "assignee": ["user@example.com"],
  "startTime": "2024-01-20T10:00:00.000Z",
  "endTime": "2024-01-20T18:00:00.000Z",
  "createdBy": "admin@example.com",
  "createdTime": "2024-01-20T09:30:00.000Z",
  "organizationId": "org_id_here",
  // All Flow component fields
  "customerName": "John Doe",
  "customerAddress": "123 Main St",
  "deliveryCoordinate": "-6.2088,106.8456",
  // ... other task fields
}
For Data Source Events (On Data Source Created): 
{
  "_id": "data_id_here",
  "dataType": "Customer",
  "dataTypeId": "datatype_id_here",
  "organizationId": "org_id_here",
  "createdTime": "2024-01-20T09:30:00.000Z",
  // All Data Type fields
  "name": "Customer Name",
  "email": "customer@example.com",
  // ... other data fields
}
For Routing Events (On Routing Finished, On Routing Dispatched): 
{
  "_id": "routing_id_here",
  "name": "Route Plan Name",
  "status": "FINISHED",
  "organizationId": "org_id_here",
  "createdTime": "2024-01-20T09:30:00.000Z",
  "vehicles": [...],
  "visits": [...],
  // ... routing result data
}

​
Use Cases

​
1. External System Integration

Scenario: Send task completion data to your ERP system. Configuration:
  • Event: On Task Finished
  • Flow: Delivery
  • Automation Type: Webhook
  • URL: https://erp.yourcompany.com/api/deliveries/complete
  • Headers:
    • Authorization: Bearer your-erp-api-token
    • Content-Type: application/json
Benefit: Real-time synchronization of delivery data with enterprise systems.

​
2. Slack Notifications

Scenario: Send notifications to Slack channel when high-priority tasks are created. Configuration:
  • Event: On Task Created
  • Flow: Urgent Delivery
  • Automation Type: Webhook
  • URL: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
  • Rules: priority = “High”
Benefit: Immediate team notification for urgent tasks.

​
3. Custom Dashboard Updates

Scenario: Update real-time dashboard when routes are dispatched. Configuration:
  • Event: On Routing Dispatched
  • Automation Type: Webhook
  • URL: https://dashboard.yourcompany.com/api/routes/update
  • Headers:
    • X-API-Key: your-dashboard-api-key
Benefit: Live dashboard updates for operations monitoring.

​
4. CRM Integration

Scenario: Create customer records in CRM when new data is added. Configuration:
  • Event: On Data Source Created
  • Flow: Customer Database
  • Automation Type: Webhook
  • URL: https://api.crm.com/contacts/create
  • Headers:
    • Authorization: Bearer crm-api-token
Benefit: Automated customer data synchronization between systems.

​
5. Billing System Integration

Scenario: Send billing data when tasks are completed. Configuration:
  • Event: On Task Finished
  • Flow: Delivery
  • Automation Type: Webhook
  • URL: https://billing.yourcompany.com/api/invoices
  • Headers:
    • X-Billing-Key: your-billing-api-key
Benefit: Automated invoice generation based on completed deliveries.

​
How It Works

  1. Event Occurs: The specified automation event is triggered
  2. Rules Evaluated: If Rules are configured, they are checked
  3. Webhook Prepared: MileApp prepares the HTTP POST request with event data as JSON payload
  4. Headers Added: Custom headers (if configured) are added to the request
  5. Request Sent: POST request is sent to the configured URL
  6. Response Logged: The response from the endpoint is logged for monitoring

​
Security Best Practices

​
1. Use HTTPS URLs

Always use HTTPS endpoints to ensure data is encrypted in transit. Good: 
https://api.example.com/webhooks/delivery
Avoid: 
http://api.example.com/webhooks/delivery

​
2. Implement Authentication

Use authentication headers to secure your webhook endpoints:
  • Bearer tokens
  • API keys
  • Custom authentication schemes

​
3. Validate Webhook Requests

On your receiving endpoint, implement validation to ensure requests are from MileApp:
  • Verify request source
  • Validate payload structure
  • Check authentication headers

​
4. Handle Secrets Securely

  • Never hardcode sensitive tokens in documentation
  • Rotate API keys regularly
  • Use environment-specific credentials

​
5. IP Whitelisting

If possible, whitelist MileApp’s IP addresses on your firewall for additional security.

​
Best Practices

  1. Test Endpoint First: Verify your webhook endpoint works before activating automation.
  2. Use Rules for Filtering: Combine with Rules to send webhooks only for specific conditions.
  3. Implement Error Handling: Ensure your endpoint handles errors gracefully and returns appropriate status codes.
  4. Log Webhook Activity: Monitor automation logs in MileApp to track webhook success/failure.
  5. Set Up Monitoring: Implement monitoring on your endpoint to track webhook delivery and processing.
  6. Document Integration: Maintain clear documentation of webhook integrations for your team.
  7. Use Descriptive Names: Name automations clearly to indicate their purpose (e.g., “Send Task Data to ERP System”).
  8. Implement Retry Logic: On your endpoint, implement retry logic for downstream operations that might fail.

​
Troubleshooting

Issue: Webhook is not being sent Possible Causes:
  • Automation is not set to Active
  • Event does not match automation configuration
  • Rules exclude the triggering event
  • URL is invalid or inaccessible
Solution:
  • Verify automation toggle is ON
  • Check Event and Flow settings
  • Review Rules configuration
  • Test URL accessibility from external network
Issue: Endpoint receives webhook but returns error Possible Causes:
  • Invalid payload structure expected by endpoint
  • Authentication failure
  • Endpoint processing error
Solution:
  • Review automation logs for response details
  • Verify authentication headers are correct
  • Check endpoint logs for error details
  • Validate payload structure matches endpoint expectations
Issue: Webhook times out Possible Causes:
  • Endpoint takes too long to respond
  • Network connectivity issues
  • Endpoint is down or unreachable
Solution:
  • Optimize endpoint response time (respond within 10 seconds)
  • Implement asynchronous processing on endpoint
  • Check endpoint availability and network connectivity
Issue: Receiving duplicate webhooks Possible Causes:
  • Multiple automation rules for same event
  • Webhook retry logic triggered by slow response
  • Endpoint not implementing idempotency
Solution:
  • Review all active automations for the same event
  • Improve endpoint response time
  • Implement idempotency checks on endpoint using event ID

​
Frequently Asked Questions

Q: What HTTP method does MileApp use for webhooks? A: MileApp sends all webhooks as HTTP POST requests with a JSON payload. Q: Can I send webhooks to multiple URLs? A: Each webhook automation sends to one URL. To send to multiple endpoints, create separate webhook automations for the same event. Q: How long does MileApp wait for a response? A: MileApp waits up to 30 seconds for a response. If your endpoint needs more time, respond with 200 OK immediately and process asynchronously. Q: Will MileApp retry failed webhooks? A: MileApp may retry webhooks that fail due to network errors or timeouts. Implement idempotency on your endpoint to handle potential duplicates. Q: Can I use webhooks with HTTP (not HTTPS)? A: Yes, but it’s strongly discouraged. Always use HTTPS to ensure data security and encryption in transit. Q: What happens if my endpoint is down? A: The webhook will fail and be logged in the automation logs. MileApp may attempt retries, but there’s no guaranteed delivery for failed webhooks. Q: Can I see the webhook request and response? A: Yes, check the automation logs (click the clock icon on the automation list) to see webhook requests, responses, and any errors. Q: How do I test webhooks without affecting production? A: Use webhook testing services like webhook.site or requestbin.com to inspect webhook payloads before connecting to your production endpoint. Q: Are there rate limits for webhooks? A: Webhooks are sent in real-time as events occur. The rate depends on your event frequency. Ensure your endpoint can handle the expected volume.