Webhooks

Webhooks allow your application to receive real-time notifications when events occur in Gatsby. On this page, we'll dive into the different webhook endpoints you can use to register and manage webhooks programmatically.

The webhook model

The webhook model contains information about the URL where notifications will be sent and the type of events that trigger the webhook.

Properties

  • Name
    webhook
    Type
    string
    Description

    The URL where webhook notifications will be sent.

  • Name
    type
    Type
    string
    Description

    The type of events that trigger the webhook. Available types are:

    • EventPerson - Triggered when changes occur to event participants
    • Event - Triggered when changes occur to events
    • GuestList - Triggered when changes occur to guest lists
POST/webhook

Register a webhook

This endpoint allows you to register a new webhook to receive notifications for specific event types.

Required attributes

  • Name
    webhook
    Type
    string
    Description

    The URL where webhook notifications will be sent.

  • Name
    type
    Type
    string
    Description

    The type of events that trigger the webhook.

Request

POST
/webhook
curl https://rest.gatsby.events/webhook \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -d '{
    "webhook": "https://example.com/webhook",
    "type": "EventPerson"
  }'

Response

{
  "success": true
}
DELETE/webhook

Remove a webhook

This endpoint allows you to remove a previously registered webhook.

Required attributes

  • Name
    webhook
    Type
    string
    Description

    The URL of the webhook to remove.

  • Name
    type
    Type
    string
    Description

    The type of the webhook to remove.

Request

DELETE
/webhook
curl -X DELETE https://rest.gatsby.events/webhook \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -d '{
    "webhook": "https://example.com/webhook",
    "type": "EventPerson"
  }'

Response

{
  "success": true
}
GET/webhook

Get sample webhook data

This endpoint allows you to retrieve sample data that would be sent to your webhooks. This is useful for testing and understanding the webhook payload format.

Request

GET
/webhook
curl https://rest.gatsby.events/webhook \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}"

Response

{
  "contacts": [
    {
      // Sample contact data that would be sent in a webhook
    }
  ]
}

Webhook payload formats

When an event occurs that matches your webhook criteria, Gatsby will send an HTTP POST request to your specified webhook URL with a JSON payload. The format of the payload depends on the webhook type:

EventPerson webhook payload

Sent when a person's status in an event changes (e.g., RSVP status updated, attendance marked).

The body is an array with one guest. Each guest has a fixed set of fields, all shown below. Webhooks don't include fields added to the REST API later, such as phone and smsConsent on Retrieve event guest list. To get those, call the REST API.

  • events - The event's name and date, such as Annual Conference 2023 - 11/15/2023.
  • email3 - A copy of email.
  • event - The event's name, date, location, and type (event or list).
  • attendanceStatus - Attended, No Show, or null when the guest has not been checked in.
  • customColumns - The guest's custom column values, keyed by column title.
[
  {
    "events": ["Annual Conference 2023 - 11/15/2023"],
    "email3": "[email protected]",
    "eventName": "Annual Conference 2023",
    "eventId": "e8dj2ns9-34kd-9j3b",
    "event": {
      "_id": "e8dj2ns9-34kd-9j3b",
      "id": "e8dj2ns9-34kd-9j3b",
      "name": "Annual Conference 2023",
      "locationName": "Moscone Center",
      "primaryDate": "2023-11-15T09:00:00.000Z",
      "locationAddress": "747 Howard St",
      "locationApartment": "",
      "locationCity": "San Francisco",
      "locationState": "CA",
      "locationPostalCode": "94103",
      "locationCountry": "USA",
      "virtualLocations": [],
      "type": "event"
    },
    "personId": "52907745-7672-470e-a",
    "firstName": "John",
    "lastName": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "rsvpStatus": "Accepted",
    "rsvpStatusHistory": [
      {
        "status": "Accepted",
        "actorType": "eventPerson",
        "actionType": "default",
        "createdAt": "2023-11-02T09:45:00.000Z"
      }
    ],
    "rsvpHardBlockedAt": null,
    "company": "Acme Inc",
    "position": "Product Manager",
    "dietaryRestrictions": ["Vegetarian"],
    "attendanceStatus": null,
    "rsvpQuestionResponses": [
      {
        "title": "Will you join the dinner?",
        "description": "",
        "answers": ["Yes"]
      }
    ],
    "rsvpNote": "Looking forward to it!",
    "customColumns": {
      "Table": "12"
    },
    "rsvpLink": "https://gatsby.events/rsvp/abc123"
  }
]

Event webhook payload

Sent when event details are updated.

{
  "eventId": "e8dj2ns9-34kd-9j3b",
  "action": "event_updated",
  "data": {
    "name": "Annual Conference 2023",
    "primaryDate": "2023-11-15T09:00:00Z",
    "updatedFields": ["name", "primaryDate"],
    "timestamp": "2023-10-25T14:30:00Z"
  }
}

GuestList webhook payload

Sent when there are bulk changes to a guest list.

The body is an array of guests, with the same fields as the EventPerson payload except events and email3. An entry is null when its guest's contact no longer exists.

[
  {
    "eventName": "Annual Conference 2023",
    "eventId": "e8dj2ns9-34kd-9j3b",
    "event": {
      "_id": "e8dj2ns9-34kd-9j3b",
      "id": "e8dj2ns9-34kd-9j3b",
      "name": "Annual Conference 2023",
      "locationName": "Moscone Center",
      "primaryDate": "2023-11-15T09:00:00.000Z",
      "locationAddress": "747 Howard St",
      "locationApartment": "",
      "locationCity": "San Francisco",
      "locationState": "CA",
      "locationPostalCode": "94103",
      "locationCountry": "USA",
      "virtualLocations": [],
      "type": "event"
    },
    "personId": "52907745-7672-470e-a",
    "firstName": "John",
    "lastName": "Doe",
    "name": "John Doe",
    "email": "[email protected]",
    "rsvpStatus": "Accepted",
    "rsvpStatusHistory": [
      {
        "status": "Accepted",
        "actorType": "eventPerson",
        "actionType": "default",
        "createdAt": "2023-11-02T09:45:00.000Z"
      }
    ],
    "rsvpHardBlockedAt": null,
    "company": "Acme Inc",
    "position": "Product Manager",
    "dietaryRestrictions": ["Vegetarian"],
    "attendanceStatus": null,
    "rsvpQuestionResponses": [
      {
        "title": "Will you join the dinner?",
        "description": "",
        "answers": ["Yes"]
      }
    ],
    "rsvpNote": "Looking forward to it!",
    "customColumns": {
      "Table": "12"
    },
    "rsvpLink": "https://gatsby.events/rsvp/abc123"
  },
  null
]

Best practices

  1. Implement idempotency: Your webhook handler should be idempotent, as Gatsby may send the same webhook multiple times if delivery confirmation fails.

  2. Respond quickly: Your webhook endpoint should respond with a 200 status code as quickly as possible. Process the webhook data asynchronously to avoid timeout issues.

  3. Verify webhook source: Consider implementing a validation mechanism to ensure the webhook is coming from Gatsby.

  4. Handle failures gracefully: Implement proper error handling and logging in your webhook handler to diagnose issues.

Was this page helpful?