Webhooks Setup Guide

Overview

A webhook is an HTTPS endpoint that you own to which Zuddl delivers a JSON payload whenever subscribed actions occur. The payload keeps you notified of the action and provides the required details. For example, a prospect registers for your flagship event, for which you need to get instantly notified to take further actions. An attendee has modified the hotel check-in date, and as an organizer, you should be notified of this action to make necessary arrangements. These are some of the many use cases of webhooks in the digital events context.

What are actions?

An action can be any discrete change in Zuddl, such as registration approved, poll answered, etc. Actions can be broadly categorized into two types:

• Org-level: platform-wide actions such as 'event created'
• Event-level: actions within specific events, such as 'ticket modified'

You can refer to the sample payloads article for all the Zuddl actions and their JSON payloads.

Creating a Webhook

Follow the steps mentioned below to create a webhook from your Zuddl dashboard.

1. From the Zuddl dashboard, go to Connections → Webhooks tab.
2. Click New webhook. (You can create up to 20 per org.)
   
   
   
3. Enter the Endpoint URL. The endpoint URL must start with 'https://'
   
   
4. Choose a Key type. 
   1. Generate key: System-generated key
   2. Assign key: Custom key
      
      
5. Enter a secret key if Assign key is selected from the previous step. If Generate key is selected, copy-paste the system-generated key.
6. Now, click Update actions to select one or more org-level and/or event-level actions.
   
   
   By default, all the actions listed here will be selected. You can proceed with all the selected actions or modify the selection and click on Update actions.”
   
   
7. Toggle On/Off Automatically include future events. 
   • When ‘On’ in any event type (Webinar, Field events, etc.,) tab, any newly created event of that type will be included automatically in that webhook. The endpoint will receive the data about the subscribed event-specific actions for the newly created event.
   • When ‘Off” in any event type (Webinar, Field events, etc.,) tab, any newly created event of that type will not be included automatically in that webhook. The endpoint will not receive the data about the subscribed event-specific actions for the newly created event.
     
     
     By default, all on-going & upcoming events will be selected 
8. Once actions are selected, click Update actions.
9. Next, you must select the events for which you need the webhooks to track action. Click the Select events button to select the required events from the list of events in your Zuddl organization.
   
   
10. Once selected, click Select events.
    
    
11. Review the settings and click Create. 

This creates the endpoint URL and it appears on the Manage webhooks page. Zuddl starts sending payloads immediately.

Payload format & signature

The webhook payload format and signature are shown below: 

Sample webhook payload

{
  "action": "EVENT_CREATED",
  "actionId": "a912a64f-8865-4289-9024-9a120792c3d8",
  "actor": {
    "id": "h212a64f-8865-4289-9024-9a120792c3d8",
    "type": "USER"
  },
  "actionCreatedAt": "2023-10-01T12:00:00Z",
  "event": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Huddle with zuddl.",
    "description": "join us to learn more about zuddl.",
    "identifier": "event-123",
    "startDate": "2025-04-11T12:30:00Z",
    "endDate": "2025-04-11T12:30:00Z",
    "timezone": "UTC/IST",
    "status": "UPCOMING/ONGOING",
    "type": "WEBINAR/FIELD_EVENT/EVENT",
    "eventFormat": "VIRTUAL/IN_PERSON/HYBRID",
    "createdAt": "2025-04-11T12:30:00Z",
    "createdBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "updatedAt": "2025-04-11T12:30:00Z",
    "updatedBy": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "teamName": "General",
    "websiteUrl": "https://app.zuddl.com/org/event",
    "parentEventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "location": {
      "venue": "string",
      "address": {
        "address": "string",
        "addressLine2": "string",
        "stateProvince": "string",
        "postalCode": "string",
        "country": "string"
      },
      "coordinates": {
        "latitude": "24.4194509",
        "longitude": "27.4194509"
      },
      "mapUrl": "https://www.google.com/maps/place/?q=place_id:ChIJ_Q8bfYdGXj4Rz1s_sFHJqcA"
    },
    "virtualEventUrl": "https://zuddl.com",
    "tags": [
      {
        "id": "tag1",
        "name": "Webinar"
      },
      {
        "id": "tag2",
        "name": "Field Event"
      }
    ]
  }
}

Refer to the sample payload of all the supported actions.

Webhook signature verification

To ensure the authenticity and integrity of the webhooks, each webhook request is signed using a secret key associated with your webhook endpoint.

How it works

    1.   We generate a signature by signing the raw webhook body (converted to string format) using the webhook secret key and a secure algorithm (HMAC-SHA256).
    2.   This signature is then included in the request as an HTTP header:

Authorization: <signature>

How to verify a webhook request

To verify the webhook request:

1. Retrieve the raw webhook body from the request.
2. Convert the body into its string format (e.g., using .toString() or equivalent in your language).
3. Use your webhook secret key to re-generate the signature using the same signing algorithm.
4. Compare your generated signature with the value in the 'Authorization' header.
   • If they match, the request is authentic.
   • If they don’t match, reject the request, as it may have been tampered with.

Managing webhooks

To any given endpoint URL, you can take the following actions:

• Edit: edit the webhook settings. Every field configuration is editable. No data is lost when you edit.
• Delete: Delete a webhook permanently
• Inactive: Pause or disable the webhook

Limits & retries