Webhooks API

Receive real-time HTTP notifications when events occur in Vellocity — listing changes, co-sell updates, and content generation completions.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token Prefix: /partners/webhooks Rate Limiting: throttle:partner

---

Endpoints

List Webhooks

GET /partners/webhooks

Parameter	Type	Required	Default	Description
per_page	integer	No	20	Items per page

Response:

{
  "data": [
    {
      "type": "webhook",
      "id": 1,
      "attributes": {
        "url": "https://your-app.com/webhooks/vellocity",
        "events": ["listing.updated", "cosell.created"],
        "description": "Production webhook",
        "active": true,
        "last_triggered_at": "2026-02-25T14:30:00Z",
        "last_response_code": 200,
        "failure_count": 0,
        "created_at": "2026-01-15T10:00:00Z"
      }
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

---

Create Webhook

POST /partners/webhooks

Parameter	Type	Required	Description
url	string	Yes	Webhook delivery URL (max 2048 chars)
events	array	Yes	Event types to subscribe to (min 1)
description	string	No	Human-readable label (max 255 chars)
active	boolean	No	Enable immediately (default: true)

Response (201):

{
  "data": {
    "type": "webhook",
    "id": 3,
    "attributes": {
      "url": "https://your-app.com/webhooks/vellocity",
      "events": ["listing.updated", "cosell.created"],
      "active": true
    }
  },
  "meta": {
    "secret": "a1b2c3d4e5f6...64chars...",
    "warning": "Store this secret securely. It will not be shown again."
  }
}

Save the secret

The webhook signing secret is returned only once in the create response. Store it securely — you need it to verify webhook signatures.

Webhook Limits by Plan

Plan	Max Webhooks
Starter	2
Accelerate	5
Command+	20
Enterprise	100

---

Delete Webhook

DELETE /partners/webhooks/{id}

Returns 204 No Content on success.

---

List Available Events

GET /partners/webhooks/events

Response:

{
  "data": [
    {
      "name": "listing.created",
      "description": "Triggered when a new marketplace listing is created",
      "payload_example": {
        "event": "listing.created",
        "listing_id": 123,
        "provider": "aws",
        "status": "pending"
      }
    },
    {
      "name": "listing.updated",
      "description": "Triggered when a listing is updated",
      "payload_example": {
        "event": "listing.updated",
        "listing_id": 123,
        "changes": ["status", "compliance_score"]
      }
    },
    {
      "name": "listing.published",
      "description": "Triggered when a listing is published to the marketplace",
      "payload_example": {
        "event": "listing.published",
        "listing_id": 123,
        "published_at": "2026-02-26T12:00:00Z"
      }
    },
    {
      "name": "listing.failed",
      "description": "Triggered when listing processing fails",
      "payload_example": {
        "event": "listing.failed",
        "listing_id": 123,
        "error": "Processing timeout"
      }
    },
    {
      "name": "cosell.created",
      "description": "Triggered when a new co-sell opportunity is created"
    },
    {
      "name": "cosell.updated",
      "description": "Triggered when a co-sell opportunity is updated"
    },
    {
      "name": "cosell.completed",
      "description": "Triggered when a co-sell opportunity is completed"
    },
    {
      "name": "content.generated",
      "description": "Triggered when AI content is generated"
    }
  ]
}

---

Test Webhook

POST /partners/webhooks/test

Parameter	Type	Required	Description
webhook_id	integer	Yes	Webhook ID to test

Sends a test payload to the webhook URL:

{
  "event": "webhook.test",
  "webhook_id": 1,
  "timestamp": "2026-02-26T10:00:00Z",
  "message": "This is a test webhook payload"
}

---

Payload Format

When events occur, Vellocity sends POST requests to your webhook URL:

POST https://your-app.com/webhooks/vellocity
Content-Type: application/json
X-Vellocity-Signature: sha256=a1b2c3d4...
X-Vellocity-Event: listing.updated
X-Vellocity-Delivery: evt_abc123

{
  "id": "evt_abc123",
  "type": "listing.updated",
  "timestamp": "2026-02-26T14:20:00Z",
  "data": {
    "listing_id": 123,
    "changes": ["status", "compliance_score"]
  }
}

---

Verifying Signatures

Validate the X-Vellocity-Signature header using the secret from webhook creation:

PythonNode.jsPHP

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# In your webhook handler:
is_valid = verify_webhook(
    request.body,
    request.headers["X-Vellocity-Signature"],
    WEBHOOK_SECRET,
)

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

function verifyWebhook(string $payload, string $signature, string $secret): bool
{
    $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

---

Use Cases

Monitor Listing Changes

1. Create a webhook: POST /partners/webhooks subscribing to listing.updated and listing.published
2. When notified, fetch the updated listing via Partner API
3. Sync changes to your internal CRM or monitoring system

Co-Sell Pipeline Automation

1. Subscribe to cosell.created and cosell.updated
2. When a new opportunity arrives, create a corresponding record in your CRM
3. When status changes, update your pipeline dashboard
4. Subscribe to cosell.completed to trigger post-deal workflows

Content Generation Monitoring

1. Subscribe to content.generated
2. When content is ready, automatically push it through your review workflow
3. Combine with the Content Workflow API kanban for full lifecycle management