Skip to main content

Webhooks

Configure outbound webhooks to notify your systems when Visual Experience Engine data changes or replication jobs run. Add an HTTPS endpoint for each category below and click Save.

Supported Webhook Types​

  • Content Webhooks
    • Triggered when content is created, updated, or deleted
    • Operations: create, update, delete
  • Scheduled Content Webhooks
    • Triggered when scheduled content is created, updated, published, archived, or deleted
    • Operations: create, update, delete
  • Screen Webhooks
    • Triggered when screens are created, updated, or deleted
    • Operations: create, update, delete
  • Replication Webhooks
    • Triggered when a replication job starts, completes, or fails
    • Operations: started, completed, failed

Endpoint Requirements​

  • Use HTTPS endpoints that respond quickly (recommended < 5s) and return a 2xx status on success.
  • Handle duplicate deliveries idempotently.
  • Log all deliveries for observability.

Event Delivery​

  • Delivery Method: POST with application/json body
  • Retries: If your endpoint returns a non-2xx status or times out, the Visual Experience Engine may retry with backoff.

Example Payloads​

Content Webhook​

{
  "operation": "update",
  "entityType": "content",
  "timestamp": "2025-01-15T18:12:03.341Z",
  "data": {
    "contentId": "abc123",
    "operation": "update",
    "data": {
      "title": "Homepage Hero",
      "status": "published",
      "slug": "homepage-hero"
    },
    "user": "user123",
    "timestamp": 1759167189263
  }
}

Scheduled Content Webhook​

{
  "operation": "update",
  "entityType": "banner",
  "timestamp": "2025-01-15T18:12:03.341Z",
  "data": {
    "bannerId": "-OaLXG4CJ8aBWj2FOXYl",
    "operation": "update",
    "data": {
      "name": "Clearance Scheduled Content",
      "published": true,
      "locations": ["/"],
      "appType": "web",
      "devices": {
        "web": true
      },
      "screenTypes": {
        "desktop": true,
        "tablet": true,
        "phone": true
      }
    },
    "user": "user123",
    "timestamp": 1759167189263
  }
}

Screen Webhook​

{
  "operation": "create",
  "entityType": "screen",
  "timestamp": "2025-01-15T18:12:03.341Z",
  "data": {
    "screenName": "Home Screen",
    "operation": "create",
    "data": {
      "versionCount": 1,
      "platforms": ["ios"],
      "createdAt": 1759184877720,
      "updatedAt": 1759184877720,
      "inProduction": false,
      "deleted": false,
      "name": "Home Screen",
      "data": {
        "components": {},
        "Test": {
          "fieldName": "Test",
          "value": "Test",
          "type": "string"
        }
      }
    },
    "user": "user123",
    "timestamp": 1759184877720
  }
}

Replication Webhooks​

Replication Started​

{
  "operation": "started",
  "entityType": "replication",
  "timestamp": "2025-01-15T18:12:03.341Z",
  "data": {
    "replicationId": "-OaMG1LIdZJsdQRmlGnE",
    "source": "belk-web-nextjs",
    "destination": "belk-web-dev",
    "status": "In Progress",
    "bannerId": "-OaLXG4CJ8aBWj2FOXYl"
  }
}

Replication Completed​

{
  "operation": "completed",
  "entityType": "replication",
  "timestamp": "2025-01-15T18:12:03.341Z",
  "data": {
    "replicationId": "-OaMG1LIdZJsdQRmlGnE",
    "source": "belk-web-nextjs",
    "destination": "belk-web-dev",
    "status": "Successful",
    "bannerId": "-OaLXG4CJ8aBWj2FOXYl",
    "completedAt": 1759179474619,
    "replicatedCount": 56,
    "replicatedIds": ["-OaLXG4CJ8aBWj2FOXYl"],
    "replicatedBannerIds": ["-OaLXG4CJ8aBWj2FOXYl"],
    "replicatedBannerCount": 1,
    "replicatedContentIds": ["-OU4Hxh5Ill39psJaT83"],
    "replicatedContentCount": 55
  }
}

Security​

  • Restrict endpoints with a firewall or allowlist where possible.
  • Validate source IPs and apply authentication (e.g., shared secret in header).
  • Verify payload integrity (e.g., signature/HMAC) if enabled for your instance.

Webhook Configuration​

Setting Up Webhooks​

  1. Access Configuration: Navigate to the Visual Experience Engine configuration section
  2. Add Endpoints: Enter HTTPS URLs for each webhook type you want to receive
  3. Test Endpoints: Use the test functionality to verify your endpoints are working
  4. Save Configuration: Click Save to activate the webhooks

Testing Webhooks​

For testing and development, you can use webhook.site to:

  • Generate unique webhook URLs
  • View real-time webhook payloads
  • Test your webhook handling logic
  • Debug payload structure and content

Webhook Triggers​

Webhooks are triggered in the following scenarios:

  • Content Changes: Any create, update, or delete operation on content items
  • Scheduled Content Changes: Any create, update, or delete operation on scheduled content
  • Screen Changes: Any create, update, or delete operation on screens
  • Replication Events: When replication jobs start, complete, or fail
  • Scheduled Replications: Both manual and scheduled replication events

Operations​

  • Returning any 2xx status acknowledges delivery
  • Use exponential backoff for downstream retries in your system to avoid thundering herds
  • Monitor for event latency and failures; consider a dead-letter queue for repeated failures
  • Each webhook includes a unique timestamp and operation type for proper event ordering