SARAH
DocumentationAPI Reference

Automation

Guide to automate processes in Sarah using webhooks and integrations

Last updated: 2025-01-26

Sarah allows you to automate processes through webhooks and integrations with platforms like Make and Zapier. This guide will help you create automated workflows to optimize your business.

Basic Concepts

What is Automation?

Automation allows different systems to work together without manual intervention:

  • Trigger: Event that starts the workflow
  • Action: Action that executes automatically
  • Workflow: Sequence of automated steps

Benefits

  • ⚡ Time savings: Eliminates repetitive tasks
  • 🎯 Accuracy: Reduces human errors
  • 📊 Visibility: Improves process tracking
  • 🔄 Scalability: Handles more volume without more staff

Automation Platforms

Make (Integromat)

Advantages:

  • Intuitive visual interface
  • Multiple operations per scenario
  • Advanced data transformations
  • Free plan available

Ideal for:

  • Complex workflows
  • Data transformations
  • Advanced integrations

Zapier

Advantages:

  • Easy to use
  • Thousands of connected applications
  • Pre-configured templates
  • Free plan available

Ideal for:

  • Simple integrations
  • Quick connections
  • Non-technical users

Sarah Webhooks

Inbound (Receive Events)

Sarah can receive events from external systems:

Endpoint:

POST /api/integration/in

Use:

  • Update products from external systems
  • Create sales from external orders
  • Sync inventory

Outbound (Send Events)

Sarah can send events to external systems:

Endpoint:

POST /api/integration/out

Use:

  • Notify new sales
  • Update external systems
  • Send alerts

Common Use Cases

1. Sync Products from Shopify

Goal: Keep products synchronized between Shopify and Sarah

Workflow:

  1. Trigger: New product in Shopify
  2. Action: Send webhook to Sarah (product.upserted)
  3. Result: Product created/updated in Sarah

Configuration in Make:

Shopify (Trigger) → HTTP Request (Action)
  - URL: https://sarah.ar/api/integration/in
  - Method: POST
  - Headers: Authorization: Bearer <integration-key>
  - Body: {
      "event": "product.upserted",
      "data": { "product": {...} }
    }

2. Notify Sales in Slack

Goal: Receive notifications in Slack when a sale is created

Workflow:

  1. Trigger: Sarah sends sales.created event
  2. Action: Make/Zapier receives webhook
  3. Action: Send message to Slack
  4. Result: Notification in Slack channel

Configuration in Zapier:

Webhook (Trigger) → Slack (Action)
  - Webhook URL: https://your-zapier-webhook.com
  - Filter: event = "sales.created"
  - Slack: Send Channel Message

3. Update Inventory in Google Sheets

Goal: Maintain an inventory record in Google Sheets

Workflow:

  1. Trigger: Sarah sends product.stock_updated event
  2. Action: Make/Zapier receives webhook
  3. Action: Update row in Google Sheets
  4. Result: Spreadsheet updated

4. Send Email when Invoice is Issued

Goal: Send invoice by email automatically

Workflow:

  1. Trigger: Sarah sends invoice.issued event
  2. Action: Make/Zapier receives webhook
  3. Action: Send email with attached invoice
  4. Result: Customer receives invoice by email

5. Create Order in Sarah from WooCommerce

Goal: Create sales in Sarah when there are orders in WooCommerce

Workflow:

  1. Trigger: New order in WooCommerce
  2. Action: Send webhook to Sarah (sales.created)
  3. Result: Sale created in Sarah

6. Alert Low Stock in Discord

Goal: Receive alerts when stock is low

Workflow:

  1. Trigger: Sarah sends product.stock_updated event
  2. Filter: If current_stock < 10
  3. Action: Send message to Discord
  4. Result: Alert in Discord channel

Step-by-Step Configuration

Step 1: Get Integration Key

  1. Log in to Sarah
  2. Go to Settings > Integrations
  3. Copy your Integration Key
  4. Save it securely

Step 2: Configure Webhook in Make/Zapier

In Make

  1. Create a new scenario
  2. Add Webhooks > Custom webhook module
  3. Copy the Webhook URL
  4. Configure this URL in Sarah (environment variable MAKER_WH_URL)

In Zapier

  1. Create a new Zap
  2. Choose Webhooks by Zapier > Catch Hook
  3. Copy the Webhook URL
  4. Configure this URL in Sarah

Step 3: Configure Security (Optional but Recommended)

HMAC Signature

  1. In Sarah: Configure MAKER_WH_HMAC_SECRET
  2. In Make/Zapier: Validate x-signature header

Validation example:

javascript
const signature = request.headers['x-signature'];
const expected = hmacSha256(secret, rawBody);
if (signature !== expected) {
  // Reject request
}

Step 4: Test Workflow

  1. Trigger an event: Create a sale or update a product
  2. Verify webhook: Check that Make/Zapier receives the event
  3. Verify action: Confirm action executes correctly
  4. Adjust if necessary: Refine workflow as needed

Best Practices

1. Idempotency

Always use x-idempotency-key to avoid duplicate processing:

javascript
const idempotencyKey = request.headers['x-idempotency-key'];
if (await isProcessed(idempotencyKey)) {
  return; // Already processed
}
await processEvent(event, data);
await markProcessed(idempotencyKey);

2. Error Handling

Implement robust error handling:

  • Retries: Retry failed requests
  • Logging: Log all errors
  • Alerts: Notify critical errors
  • Fallbacks: Have alternative plans

3. Validation

Validate all data before processing:

  • Structure: Verify data has correct structure
  • Types: Validate data types
  • Ranges: Verify values within valid ranges

4. Performance

Optimize your workflows:

  • Early filters: Filter unnecessary events as early as possible
  • Async processing: Don't block the webhook
  • Rate limiting: Respect rate limits
  • Caching: Cache data that doesn't change frequently

5. Security

Protect your integrations:

  • HTTPS always: Never use HTTP
  • HMAC signatures: Validate data integrity
  • Secure tokens: Never expose tokens publicly
  • Replay protection: Validate timestamps

Troubleshooting

Webhook doesn't arrive

  1. Verify URL: Ensure it's correct and accessible
  2. Review logs: Look for errors in Sarah
  3. Test manually: Send a test event
  4. Verify configuration: Review environment variables

Duplicate events

  1. Implement idempotency: Use x-idempotency-key
  2. Verify retries: Ensure there are no unnecessary retries
  3. Review logs: Identify source of duplicates

Processing errors

  1. Review structure: Verify data is correct
  2. Validate permissions: Ensure you have necessary permissions
  3. Review logs: Look for specific errors
  4. Test incrementally: Test each step of the workflow

Additional Resources

Support

If you need help with automation:

  1. Review this guide and webhook documentation
  2. Verify configuration in Sarah and Make/Zapier
  3. Review logs to identify errors
  4. Contact Sarah support with problem details