Viewcy Webhooks Documentation

Viewcy's webhook system allows your application to receive real-time updates about events occurring in your Viewcy account. This document provides an overview of how to set up and use webhooks with Viewcy.

Overview

Webhooks are user-defined HTTP callbacks that are triggered by specific events in Viewcy. When an event occurs, Viewcy sends an HTTP POST request to the URL you configured, with information about the event in the request body.

Setting up Webhooks

You can set up webhooks through the Viewcy management interface:

1. Navigate to your profile management page
2. Select "Webhooks" from the menu
3. Click "Add Webhook"
4. Enter a name for your webhook
5. Enter the URL where you want to receive webhook notifications
6. Select the events you want to be notified about
7. Save your webhook

Event Types

Viewcy supports the following event types:

• order.created - Triggered when a new order is created
• order.completed - Triggered when an order is completed
• ticket.issued - Triggered when a new registration is created
• ticket.cancelled - Triggered when a registration is cancelled
• ticket.refunded - Triggered when a registration is refunded
• ticket.transferred - Triggered when a registration is transferred
• ticket.checked_in - Triggered when a registration is checked in
• ticket.checked_out - Triggered when a registration is checked out
• membership.subscription.created - Triggered when a new membership subscription is created
• membership.subscription.updated - Triggered when a membership subscription is updated
• membership.subscription.cancelled - Triggered when a membership subscription is cancelled
• membership.subscription.expired - Triggered when a membership subscription expires

Webhook Payload

When an event occurs, Viewcy sends an HTTP POST request to your webhook URL with a JSON payload. The payload includes:

{
  "id": "0195ce14-f24a-7bd8-84e8-f1742826d0f1",
  "event": "order.completed",
  "created_at": "2025-03-25T12:00:00Z",
  "version": "2025_06",
  "data": {
    // Event-specific data
  }
}

Security

Each webhook includes a signature in the X-Viewcy-Webhook-Signature header. You should verify this signature to ensure the webhook came from Viewcy.

The signature is an HMAC SHA-256 hash of the request body, using your webhook's secret key as the secret.

Example signature verification:

ruby

def verify_webhook_signature(payload_body, signature, secret)
  calculated_signature = OpenSSL::HMAC.hexdigest(
    OpenSSL::Digest.new('sha256'),
    secret,
    payload_body
  )
  
  calculated_signature == signature
end

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payloadBody, signature, secret) {
  const calculatedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadBody, 'utf8')
    .digest('hex');
    
  return calculatedSignature === signature;
}

TypeScript

import * as crypto from 'crypto';

function verifyWebhookSignature(
  payloadBody: string,
  signature: string,
  secret: string
): boolean {
  const calculatedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadBody, 'utf8')
    .digest('hex');
    
  return calculatedSignature === signature;
}

python

import hmac
import hashlib

def verify_webhook_signature(payload_body, signature, secret):
    calculated_signature = hmac.new(
        secret.encode('utf-8'),
        payload_body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return calculated_signature == signature

Retrying Failed Webhooks

Viewcy will automatically retry failed webhook deliveries with an exponential backoff strategy. The system attempts delivery a maximum of 5 times before marking the webhook as failed.

You can also manually retry failed webhook deliveries from the webhook events dashboard.

Managing Webhooks

• Listing Webhooks: View all your webhooks in the webhooks dashboard
• Updating Webhooks: Edit webhook details including URL, events, and description
• Disabling Webhooks: Temporarily stop receiving webhooks by setting status to "inactive"
• Deleting Webhooks: Permanently remove a webhook
• Viewing Event History: See a history of webhook events and their delivery status