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
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 theX-EcoEvents-Signature header.
Verification Process
- Extract the signature from the
X-EcoEvents-Signatureheader - Compute HMAC SHA-256 of the raw request body using your webhook secret
- 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 uniqueid field to implement idempotency in your webhook handler.
Error Responses
object
Error details