Skip to main content

Overview

The Webhooks API allows you to receive real-time notifications about events in your EcoEvents account. Configure webhook endpoints to be notified when events are created, updated, attendees register, sustainability goals are achieved, and more.

Authentication

All API requests require an API key to be included in the header:

Create Webhook

POST /api/webhooks

Register a new webhook endpoint to receive event notifications.

Request

string
required
The HTTPS URL where webhook payloads will be sent. Must use HTTPS protocol.
array
required
Array of event types to subscribe to. See Event Types for available options.
string
Optional description for this webhook
string
Optional secret for webhook signature verification. If not provided, one will be generated.
boolean
default:"true"
Whether the webhook is active
object
Optional metadata as key-value pairs

Response

string
Unique identifier for the webhook
string
The webhook endpoint URL
array
Subscribed event types
string
Webhook description
string
Secret for signature verification (shown only once during creation)
boolean
Whether the webhook is active
object
Custom metadata
string
Timestamp when webhook was created
string
Timestamp when webhook was last updated

Example

Response Example

The webhook secret is only shown once during creation. Store it securely as you’ll need it to verify webhook signatures.

List Webhooks

GET /api/webhooks

Retrieve all configured webhooks for your account.

Query Parameters

boolean
Filter by active status
integer
default:"1"
Page number for pagination
integer
default:"20"
Number of webhooks per page (max 100)

Response

array
Array of webhook objects (without secrets)
object
Pagination information

Example


Delete Webhook

DELETE /api/webhooks/:id

Remove a webhook endpoint. This action cannot be undone.

Path Parameters

string
required
The unique identifier of the webhook to delete

Response

boolean
Indicates whether the deletion was successful
string
Confirmation message
string
The ID of the deleted webhook

Example


Event Types

Available Event Types

Subscribe to the following event types when creating webhooks:

Event Events

event
Triggered when a new event is created
event
Triggered when an event is updated
event
Triggered when an event is deleted
event
Triggered when an event status changes to published
event
Triggered when an event is cancelled
event
Triggered when an event is marked as completed

Attendee Events

event
Triggered when a new attendee registers
event
Triggered when attendee information is updated
event
Triggered when an attendee cancels their registration
event
Triggered when an attendee checks in at the event

Sustainability Events

event
Triggered when a sustainability goal is achieved
event
Triggered when a carbon offset contribution is made
event
Triggered when a sustainability report is generated

Analytics Events

event
Triggered when an analytics report is ready
event
Triggered when a configured metric threshold is exceeded

Webhook Payload Structure

All webhook requests include the following structure:

Headers

Payload


Event Payload Examples

event.created

attendee.registered

sustainability.goal_achieved


Verifying Webhook Signatures

To ensure webhook requests are genuinely from EcoEvents, verify the signature in the X-EcoEvents-Signature header.

Verification Process

  1. Extract the signature from the X-EcoEvents-Signature header
  2. Compute HMAC SHA-256 of the raw request body using your webhook secret
  3. Compare the computed signature with the received signature

Example Implementation


Best Practices

Use HTTPS

Always use HTTPS URLs for webhook endpoints to ensure data security.

Verify Signatures

Always verify webhook signatures to prevent unauthorized requests.

Respond Quickly

Return a 200 status code within 5 seconds to acknowledge receipt.

Process Async

Process webhook payloads asynchronously to avoid timeouts.

Retry Logic

EcoEvents will retry failed webhook deliveries:
  • Immediate retry on timeout or 5xx error
  • 3 additional retries with exponential backoff (1min, 10min, 1hr)
  • Webhooks are disabled after 10 consecutive failures

Idempotency

Webhook events may be delivered more than once. Use the unique id field to implement idempotency in your webhook handler.

Error Responses

object
Error details

Common Error Codes