Subscribing to Events

Create webhook subscriptions to receive real-time event notifications from VelaFlows. Subscriptions are managed through the Integrations API.

Creating a Subscription

Send a POST request to create a webhook subscription:

cURL


curl -X POST https://api.velaflows.com/api/v1/integrations/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/velaflows",
    "events": [
      "inbox.conversation.created",
      "inbox.message.received",
      "crm.lead.stage_changed"
    ],
    "secret": "whsec_your_signing_secret_here"
  }'

JavaScript (Node.js)


const response = await fetch('https://api.velaflows.com/api/v1/integrations/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'x-workspace-id': 'YOUR_WORKSPACE_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-server.com/webhooks/velaflows',
    events: [
      'inbox.conversation.created',
      'inbox.message.received',
      'crm.lead.stage_changed',
    ],
    secret: 'whsec_your_signing_secret_here',
  }),
});
 
const { data } = await response.json();
console.log('Subscription ID:', data.subscription._id);

Python


import requests
 
response = requests.post(
    'https://api.velaflows.com/api/v1/integrations/webhooks',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'x-workspace-id': 'YOUR_WORKSPACE_ID',
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://your-server.com/webhooks/velaflows',
        'events': [
            'inbox.conversation.created',
            'inbox.message.received',
            'crm.lead.stage_changed',
        ],
        'secret': 'whsec_your_signing_secret_here',
    },
)
 
data = response.json()
print('Subscription ID:', data['data']['subscription']['_id'])

Subscription Fields

Field	Type	Required	Description
`url`	string	Yes	The HTTPS URL to receive webhook deliveries
`events`	string[]	Yes	Array of event types to subscribe to
`secret`	string	No	Signing secret for HMAC-SHA256 signature verification
`active`	boolean	No	Whether the subscription is active (default: `true`)

Requirements

HTTPS required — Webhook URLs must use HTTPS (HTTP is rejected)
Public endpoint — The URL must be publicly accessible from the internet
Fast response — Return a 200 status within 10 seconds
Idempotent handler — Handle duplicate deliveries gracefully using the eventId

Listing Subscriptions


curl https://api.velaflows.com/api/v1/integrations/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Updating a Subscription

Update the events or URL for an existing subscription:


curl -X PATCH https://api.velaflows.com/api/v1/integrations/webhooks/SUBSCRIPTION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["inbox.conversation.created", "crm.lead.created"],
    "active": true
  }'

Deleting a Subscription


curl -X DELETE https://api.velaflows.com/api/v1/integrations/webhooks/SUBSCRIPTION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Testing Webhooks Locally

For local development, use a tunneling tool to expose your local server:


# Using ngrok
ngrok http 3000
 
# Use the HTTPS URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/velaflows

Then create a subscription pointing to your tunnel URL and trigger events from the VelaFlows dashboard to verify delivery.