Webhooks

Webhooks

Webhooks let wrrk send real-time notifications to your application when events occur. Instead of polling the API, your server receives an HTTP POST request whenever something happens.

Setting Up Webhooks

1. Go to Settings > API > Webhooks.
2. Click Create Webhook.
3. Enter:

• URL: The endpoint on your server that will receive webhook events.
• Events: Select which events to subscribe to.
• Secret: A secret string used to verify webhook authenticity.

1. Click Save.

Available Events

Contact Events:

• contact.created, A new contact is added.
• contact.updated, A contact's fields change.
• contact.deleted, A contact is removed.

Deal Events:

• deal.created, A new deal is created.
• deal.updated, Deal fields or stage change.
• deal.closed, A deal is closed (won or lost).

Message Events:

• email.received, An email is received.
• email.sent, An email is sent from wrrk.
• whatsapp.received, A WhatsApp message is received.
• whatsapp.sent, A WhatsApp message is sent.

Workflow Events:

• workflow.executed, A workflow completed execution.
• workflow.failed, A workflow execution failed.

Webhook Payload

Each webhook delivers a JSON payload:

{
  "event": "contact.created",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "id": "cnt_abc123",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "org_id": "org_xyz"
}

Verifying Webhooks

To ensure a webhook came from wrrk, verify the X-Wrrk-Signature header:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(requestBody)
  .digest('hex');

if (signature === request.headers['x-wrrk-signature']) {
  // Webhook is authentic
}

Retry Policy

If your endpoint returns a non-2xx status code, wrrk retries the webhook:

• 1st retry: After 1 minute
• 2nd retry: After 5 minutes
• 3rd retry: After 30 minutes
• 4th retry: After 2 hours
• 5th retry: After 24 hours

After 5 failed attempts, the webhook is marked as failed and you receive an email notification.

Testing Webhooks

Click Send Test Event on any webhook configuration to send a sample payload to your endpoint. Use this during development to verify your handler works correctly.