External triggers

External triggers are a powerful integration feature that enables real-time automation and communication between different systems and applications. By using external triggers, you can automatically execute actions in your system when specific events occur elsewhere.

Common use cases include:

• Automatically sync inventory levels when warehouse stock changes in your ERP system
• Instantly create new products when supplier catalogs are updated
• Dynamically adjust product prices in response to competitor price changes
• Generate customer accounts when leads convert in your CRM system
• Update order statuses automatically upon shipping carrier confirmations
• Modify product availability based on real-time weather conditions
• Schedule seasonal discounts according to your marketing calendar
• Adjust customer tier status based on loyalty program activity

Instead of constantly polling external systems for changes or manually transferring data, external triggers provide an efficient, event-driven approach to system integration. They help reduce latency, minimize resource usage, and ensure your systems stay synchronized in real-time.

External triggers allow you to react to events from external systems by exposing an API endpoint. When an event occurs in the external system, it sends event-related payload data to your hook's endpoint, which you can use to perform specific actions. This enables integration with various systems like Zapier, Stripe, or custom scripts.

Setting up an external trigger

1) On the "Trigger" tab of your hook, select "External" as the trigger type

2) Press the "Select" button to confirm your selection

3) Configure the authentication method (see Authentication Methods below)

4) Customize the sample payload for testing if needed

5) Save the hook

Once saved, you'll receive a unique endpoint URL where external systems can send HTTP POST requests.

Authentication Methods

To secure your endpoint, you must choose one of the following authentication methods:

Bearer Token

• Sends API key in "authentication" header
• Uses "Bearer" authentication scheme
• Requires API key generation (on the “Settings” page)
• Recommended for partner applications and scripts

API Key

• Sends API key via HTTP header or query parameter
• Customizable parameter name
• Requires API key generation (on the “Settings” page)
• Recommended for scripts and webhooks (query parameter)

HTTP Basic

• Uses username/password authentication
• Sends credentials in "authentication" header
• Uses "Basic" scheme
• Recommended for partner applications where only HTTP Basic authentication is supported

HMAC

• Supports multiple algorithms (SHA-1, SHA-256, SHA-512, MD5)
• Configurable encoding (base64, base64 URL, hex)
• Customizable header name for HMAC signature
• Requires signing secret
• Recommended for webhooks of external systems

Testing Your Hook

After setting up your external trigger, you can test it using the provided curl example. This example automatically includes:

• Your hook's unique endpoint URL
• The configured authentication method and credentials
• The sample payload you customized during setup

To test your hook:

1. Ensure your hook is activated
2. Copy the curl example provided in the interface
3. Replace YOUR_API_KEY_HERE in the example with your actual API key
4. Paste and run the command in your terminal

Example curl command (will vary based on your authentication method):

curl -X POST "https://your-endpoint-url/api/v1/hooks/your-hook-id/run" \
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
  "key1": "value1",
  "key2": "value2"
}'

The curl command will send your sample payload to the hook, allowing you to verify that:

• Your authentication is properly configured
• Your endpoint is accessible
• Your hook processes the payload as expected

If your request is successful the endpoint will return HTTP code 200 and “OK” in the body of the response. For additional status codes, please refer to the “Error handling and Troubleshooting“ section below.

Error handling and Troubleshooting

Rate limits

Rate limits apply to every account, and exceeding the limits mean that the sender has to wait until the quota is reset.

By default, the rate limits are:

• Minutely: 200
• Hourly: 1000
• Daily: 5000

If you need higher rate limits then please contact our support team.

When rate limits are exceeded, the API will return a 429 status code along with the following headers:

• X-RateLimit-Limit: Your total quota
• X-RateLimit-Remaining: Number of requests remaining
• X-RateLimit-Reset: Time when the quota will reset (Unix timestamp)

Status Codes

When sending requests to external triggers, you may encounter these HTTP status codes:

• 200: Success - Request processed successfully
• 400: Bad Request - Invalid payload format or missing required fields
• 401: Unauthorized - Invalid authentication credentials
• 429: Too Many Requests - Rate limit exceeded
• 500: Internal Server Error - Server-side processing error

Common Issues and Solutions

Authentication Failures (401)

• Verify your API key or token is correct and not expired
• Check if the authentication credentials are properly formatted in the request header
• Ensure you're using the correct authentication method (Bearer Token, API Key, HTTP Basic, or HMAC)

Invalid Payload (400)

• Validate your JSON payload structure before sending

Rate Limiting (429)

• Implement exponential backoff retry logic
• Monitor X-RateLimit-* headers to track your quota usage

Connection Issues

• Set appropriate request timeouts (recommended: 30 seconds)
• Implement retry logic for failed requests
• Log request/response details for debugging
• Check your network connectivity and firewall settings