Webhooks

Webhooks let systems outside PrimeCal trigger your automation rules automatically. When an external service — a booking platform, a CRM, a web store — posts a JSON message to your rule's webhook URL, PrimeCal receives it and runs the rule.

How Webhooks Work

Every automation rule that uses the webhook.incoming trigger gets its own unique URL. When a third-party system sends an HTTP POST request to that URL with a JSON body, your rule fires.

The flow is:

1. External system sends a POST request to your webhook URL
2. PrimeCal receives the payload and logs it
3. The rule's conditions are evaluated against the payload data
4. If conditions match (or there are no conditions), the action runs

Finding Your Webhook URL

1. Go to Dashboard → Automation
2. Open the rule you want to connect (or create a new one with webhook.incoming as the trigger)
3. In the rule detail view, open the Webhook tab
4. Copy the URL — it looks like:

   https://app.primecal.eu/api/automation/webhooks/abc123xyz/receive

Each rule has a different token in the URL. This token is your security key.

Keep your webhook URL private

Anyone who has the URL can trigger your rule. Treat it like a password. If the URL is ever exposed, regenerate the token from the rule's Webhook tab.

Sending a Webhook Request

Your external system needs to send a POST request to the webhook URL with Content-Type: application/json.

Example payload:

{
  "event": "order.completed",
  "data": {
    "order_id": "12345",
    "customer": "John Doe",
    "total": 99.99,
    "status": "paid"
  }
}

PrimeCal accepts any valid JSON structure. The top-level shape is flexible — you can use data, payload, body, or any nesting you prefer. What matters is that you reference the same paths in your conditions using dot notation (e.g., webhook.data.order_id).

Testing with curl

You can test your webhook from a terminal before wiring up your external system:

curl -X POST https://app.primecal.eu/api/automation/webhooks/YOUR_TOKEN/receive \
  -H "Content-Type: application/json" \
  -d '{"event":"test","data":{"priority":"high","customer_id":"123"}}'

Replace YOUR_TOKEN with the token from your rule's Webhook tab. After sending, check the rule's History tab in PrimeCal to confirm the request was received and logged.

You can also use Postman or any HTTP client that lets you set headers and send a JSON body.

Using Payload Data in Conditions

Once a webhook arrives, you can inspect its contents inside conditions using webhook.data with dot notation:

• webhook.data.order_id → the order_id field under data
• webhook.data.customer → the customer field under data
• webhook.data.status → the status field under data

Example rule: Only act when status equals "paid":

• Condition field: webhook.data.status
• Operator: equals
• Value: paid

See Smart Values for a full explanation of dot notation and nested access.

Practical Example: Booking Confirmation

A reservation platform sends a webhook to PrimeCal when someone books a pool session. The payload looks like:

{
  "event": "booking.confirmed",
  "data": {
    "booking_id": "bk_001",
    "guest_name": "Sarah Connor",
    "slot": "2026-07-15T10:00:00",
    "type": "pool"
  }
}

You want to color-code all incoming pool bookings in cyan so they stand out on the calendar.

Rule setup:

1. Trigger: webhook.incoming
2. Condition: webhook.data.type equals pool
3. Action: Set event color → Cyan

When the reservation system fires the webhook, PrimeCal receives it, checks that type is pool, and applies the cyan color to the associated event.

Regenerating a Webhook Token

If you suspect your webhook URL has been exposed or you want to rotate it as a precaution:

1. Open the rule in the rule detail view
2. Go to the Webhook tab
3. Click Regenerate Token
4. Update your external system with the new URL

The old URL stops working immediately after regeneration.

Checking Webhook Logs

Every webhook request — whether it triggered the action or was filtered out by conditions — is logged in the rule's audit trail.

1. Open the rule detail view
2. Go to the History tab
3. Each entry shows the timestamp, the incoming payload, which conditions were evaluated, and the outcome

This is the first place to check if a webhook doesn't seem to be working.

Troubleshooting

If your webhook isn't triggering the rule as expected, see Troubleshooting Automations for a full checklist. The most common issues are:

• Wrong Content-Type header (must be application/json)
• Token in the URL doesn't match the current rule token
• A condition is filtering out the request (check the History tab for the reason)

---

Last updated: 2026-06-30 | PrimeCal v1.3.4