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).

{
  "eventId": "e8dj2ns9-34kd-9j3b",
  "personId": "52907745-7672-470e-a",
  "action": "rsvp_updated",
  "data": {
    "rsvpStatus": "Accepted",
    "previousStatus": "Invited",
    "timestamp": "2023-11-02T09:45:00Z"
  }
}

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.

{
  "eventId": "e8dj2ns9-34kd-9j3b",
  "action": "guestlist_updated",
  "data": {
    "addedCount": 5,
    "removedCount": 2,
    "updatedCount": 10,
    "timestamp": "2023-10-25T14:30:00Z"
  }
}

Best practices

Implement idempotency: Your webhook handler should be idempotent, as Gatsby may send the same webhook multiple times if delivery confirmation fails.
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.
Verify webhook source: Consider implementing a validation mechanism to ensure the webhook is coming from Gatsby.
Handle failures gracefully: Implement proper error handling and logging in your webhook handler to diagnose issues.