Webhooks & External Triggers

Webhooks allow external systems to trigger automation rules in Terragnos Core, and enable Terragnos Core to notify external systems about events. This guide covers both incoming webhooks (triggers) and outgoing webhooks (notifications).

Incoming Webhooks (Triggers)

Incoming webhooks allow external systems to trigger automation rules in Terragnos Core.

Creating a Webhook Trigger

First, create an automation rule with a webhook trigger:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "external-notification-handler",
    "trigger": {
      "type": "webhook",
      "slug": "external-system"
    },
    "match": {
      "type": "attribute",
      "path": "$.event",
      "operator": "equals",
      "value": "inspection-completed"
    },
    "effect": {
      "type": "workflow.transition",
      "targetState": "approved"
    }
  }' \
  https://core.example.com/v1/automation/rules

Calling a Webhook

Send a POST request to the webhook endpoint:

curl -X POST \
  -H "Authorization: Bearer <webhook-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "inspection-completed",
    "objectId": "object-123",
    "metadata": {
      "inspector": "John Doe",
      "result": "passed"
    }
  }' \
  https://core.example.com/v1/automation/triggers/external-system

Webhook Authentication

Webhook endpoints require authentication. Generate a webhook token when creating the automation rule, or use a pre-configured token.

The token must be included in the Authorization header:

Authorization: Bearer <webhook-token>

Webhook Payload

The webhook payload is passed to the automation rule's match conditions. Structure your payload to match your rule's match conditions:

{
  "event": "inspection-completed",
  "objectId": "object-123",
  "objectTypeId": "inspection-request",
  "metadata": {
    "inspector": "John Doe",
    "result": "passed",
    "score": 95
  }
}

Outgoing Webhooks (Notifications)

Automation rules can call external webhooks to notify other systems about events.

Configuring Outgoing Webhooks

Add a webhook effect to your automation rule:

{
  "effect": {
    "type": "webhook",
    "url": "https://external-system.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{webhook-secret}}",
      "X-Custom-Header": "value"
    },
    "body": {
      "objectId": "{{object.id}}",
      "event": "object-approved",
      "timestamp": "{{now}}",
      "metadata": {
        "workflowState": "{{object.workflowState}}"
      }
    },
    "retry": {
      "maxAttempts": 3,
      "backoff": "exponential"
    }
  }
}

Webhook Templates

Use template variables in webhook configurations:

• {{object.id}} – Object ID
• {{object.typeId}} – Object type ID
• {{object.workflowState}} – Current workflow state
• {{object.attributes.field}} – Object attribute value
• {{now}} – Current timestamp
• {{tenant}} – Tenant ID

Retry Logic

Webhook calls automatically retry on failure:

• Max attempts: Configurable (default: 3)
• Backoff: Exponential (1s, 2s, 4s, ...)
• Timeout: 30 seconds per attempt

Failed webhooks are logged in the automation rule execution history.

Webhook Security

Signature Validation

For incoming webhooks, validate signatures to ensure requests are authentic:

1. Generate a shared secret
2. Include the secret in webhook token configuration
3. Validate signatures in your automation rule conditions

HTTPS Only

Always use HTTPS for webhook URLs in production. HTTP is only acceptable for local development.

Token Rotation

Rotate webhook tokens regularly:

1. Generate a new token
2. Update automation rules with the new token
3. Update external systems to use the new token
4. Remove old tokens

Monitoring

Monitor webhook execution:

# View webhook executions
curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/automation/rules/{ruleId}/runs

# View specific execution
curl -H "Authorization: Bearer <token>" \
  https://core.example.com/v1/automation/rules/{ruleId}/runs/{runId}

Execution logs include:

• Request/response details
• Execution time
• Success/failure status
• Error messages (if any)

Best Practices

1. Use HTTPS – Always use HTTPS for webhook URLs
2. Validate signatures – Verify incoming webhook authenticity
3. Handle timeouts – External systems may be slow or unavailable
4. Implement idempotency – Design webhooks to be safely retried
5. Log everything – Keep detailed logs of webhook calls
6. Monitor failures – Set up alerts for webhook failures
7. Rate limit – Be mindful of external system rate limits
8. Use retries – Configure appropriate retry policies