Webhooks

Webhooks notify your application when events occur in Workestra. Build real-time integrations without polling.

webhooks configuration

Screenshot needed � add an annotated image showing this UI

What Are Webhooks?

Webhooks are HTTP callbacks:

Event occurs in Workestra
HTTP POST sent to your URL
Your application receives data
Your application processes event

Webhooks are more efficient than polling. You receive events instantly instead of checking periodically.

Available Events

CRM Events

Event	Description
`contact.created`	New contact added
`contact.updated`	Contact modified
`contact.deleted`	Contact removed
`deal.created`	New deal created
`deal.updated`	Deal changed
`deal.stage_changed`	Deal moved stages
`deal.won`	Deal closed won
`deal.lost`	Deal closed lost
`activity.created`	Activity logged

Recruiting Events

Event	Description
`candidate.created`	New candidate applied
`candidate.updated`	Candidate modified
`job.created`	New job posted
`application.received`	Application submitted
`interview.scheduled`	Interview booked

Project Events

Event	Description
`task.created`	Task created
`task.updated`	Task modified
`task.completed`	Task marked done
`cycle.started`	Cycle began
`cycle.ended`	Cycle completed

Finance Events

Event	Description
`invoice.created`	Invoice generated
`invoice.paid`	Payment received
`invoice.overdue`	Invoice past due
`expense.created`	Expense logged

Support Events

Event	Description
`ticket.created`	Ticket received
`ticket.updated`	Ticket modified
`ticket.resolved`	Ticket closed
`ticket.escalated`	Priority increased

Setting Up Webhooks

Step 1: Create Endpoint

Your application needs a URL that accepts POST requests:

https://your-app.com/webhooks/workestra

Step 2: Configure in Workestra

Go to Settings > API > Webhooks
Click New Webhook
Enter:
- URL — Your endpoint
- Events — Select which events
- Secret — For signature verification
Save

Step 3: Verify Endpoint

Workestra sends test event:

{
  "type": "endpoint.verify",
  "id": "evt_test_123",
  "created_at": "2024-03-15T10:00:00Z"
}

Your endpoint must respond with 200 OK.

Webhook Payload

Event Structure

{
  "id": "evt_1234567890",
  "type": "contact.created",
  "created_at": "2024-03-15T10:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "id": "con_def456",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "company": "Acme Corp",
    "created_at": "2024-03-15T10:30:00Z"
  }
}

Common Fields

Field	Description
`id`	Unique event ID
`type`	Event type
`created_at`	When event occurred
`workspace_id`	Source workspace
`data`	Event-specific data

Security

Signature Verification

Verify webhooks came from Workestra:

X-Workestra-Signature: sha256=<hex>

Verification code:

import hmac
import hashlib

secret = b'your_webhook_secret'
payload = request.body
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()

if signature == request.headers['X-Workestra-Signature']:
    # Valid webhook
else:
    # Invalid, reject

HTTPS Only

Webhook URLs must use HTTPS for security.

IP Allowlist

Webhook requests come from these IPs:

203.0.113.0/24
198.51.100.0/24

Handling Webhooks

Best Practices

Respond quickly — Return 200 ASAP, process async
Idempotency — Handle duplicate events gracefully
Retries — Workestra retries on failure
Order — Events may arrive out of order

Retry Policy

If your endpoint fails:

Attempt	Delay
1	Immediate
2	5 seconds
3	30 seconds
4	2 minutes
5	10 minutes

After 5 failures, webhook disabled.

Example Handler

app.post('/webhooks/workestra', (req, res) => {
  // Respond immediately
  res.sendStatus(200);
  
  // Process async
  const event = req.body;
  
  switch(event.type) {
    case 'contact.created':
      handleNewContact(event.data);
      break;
    case 'deal.won':
      handleWonDeal(event.data);
      break;
  }
});