Webhooks API - EcoEvents

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:

Authorization: Bearer YOUR_API_KEY

Create Webhook

POST /api/webhooks

Request

url

string

required

The HTTPS URL where webhook payloads will be sent. Must use HTTPS protocol.

events

array

required

Array of event types to subscribe to. See Event Types for available options.

description

string

Optional description for this webhook

secret

string

Optional secret for webhook signature verification. If not provided, one will be generated.

active

boolean

default:"true"

Whether the webhook is active

metadata

object

Optional metadata as key-value pairs

Response

string

Unique identifier for the webhook

url

string

The webhook endpoint URL

events

array

Subscribed event types

description

string

Webhook description

secret

string

Secret for signature verification (shown only once during creation)

active

boolean

Whether the webhook is active

metadata

object

Custom metadata

createdAt

string

Timestamp when webhook was created

updatedAt

string

Timestamp when webhook was last updated

Example

curl -X POST https://api.ecoevents.com/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhook-handler",
    "events": [
      "event.created",
      "event.updated",
      "attendee.registered",
      "sustainability.goal_achieved"
    ],
    "description": "Production webhook for event notifications",
    "metadata": {
      "environment": "production",
      "team": "events"
    }
  }'

Response Example

{
  "id": "wh_9m8n7o6p5q4r",
  "url": "https://your-domain.com/webhook-handler",
  "events": [
    "event.created",
    "event.updated",
    "attendee.registered",
    "sustainability.goal_achieved"
  ],
  "description": "Production webhook for event notifications",
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "active": true,
  "metadata": {
    "environment": "production",
    "team": "events"
  },
  "createdAt": "2026-03-05T12:00:00Z",
  "updatedAt": "2026-03-05T12:00:00Z"
}

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

active

boolean

Filter by active status

page

integer

default:"1"

Page number for pagination

limit

integer

default:"20"

Number of webhooks per page (max 100)

Response

webhooks

array

Array of webhook objects (without secrets)

pagination

object

Pagination information

Example

curl -X GET "https://api.ecoevents.com/api/webhooks?active=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

success

boolean

Indicates whether the deletion was successful

message

string

Confirmation message

deletedId

string

The ID of the deleted webhook

Example

curl -X DELETE https://api.ecoevents.com/api/webhooks/wh_9m8n7o6p5q4r \
  -H "Authorization: Bearer YOUR_API_KEY"

Event Types

Available Event Types

Subscribe to the following event types when creating webhooks:

Event Events

event.created

event

Triggered when a new event is created

event.updated

event

Triggered when an event is updated

event.deleted

event

Triggered when an event is deleted

event.published

event

Triggered when an event status changes to published

event.cancelled

event

Triggered when an event is cancelled

event.completed

event

Triggered when an event is marked as completed

Attendee Events

attendee.registered

event

Triggered when a new attendee registers

attendee.updated

event

Triggered when attendee information is updated

attendee.cancelled

event

Triggered when an attendee cancels their registration

attendee.checked_in

event

Triggered when an attendee checks in at the event

Sustainability Events

sustainability.goal_achieved

event

Triggered when a sustainability goal is achieved

sustainability.carbon_offset

event

Triggered when a carbon offset contribution is made

sustainability.report_generated

event

Triggered when a sustainability report is generated

Analytics Events

analytics.report_ready

event

Triggered when an analytics report is ready

analytics.threshold_exceeded

event

Triggered when a configured metric threshold is exceeded

Webhook Payload Structure

All webhook requests include the following structure:

Headers

Content-Type: application/json
X-EcoEvents-Signature: sha256=<signature>
X-EcoEvents-Event: <event_type>
X-EcoEvents-Delivery: <unique_delivery_id>
User-Agent: EcoEvents-Webhooks/1.0

Payload

{
  "id": "evt_delivery_123abc",
  "type": "event.created",
  "createdAt": "2026-03-05T12:30:00Z",
  "data": {
    // Event-specific payload
  },
  "account": {
    "id": "acc_xyz789",
    "name": "Your Organization"
  }
}

Event Payload Examples

event.created

{
  "id": "evt_delivery_123abc",
  "type": "event.created",
  "createdAt": "2026-03-05T12:30:00Z",
  "data": {
    "event": {
      "id": "evt_1a2b3c4d5e6f",
      "name": "Sustainable Tech Summit 2026",
      "startDate": "2026-06-15T09:00:00Z",
      "endDate": "2026-06-17T18:00:00Z",
      "location": {
        "city": "San Francisco",
        "country": "US"
      },
      "status": "draft"
    }
  },
  "account": {
    "id": "acc_xyz789",
    "name": "GreenTech Events"
  }
}

attendee.registered

{
  "id": "evt_delivery_456def",
  "type": "attendee.registered",
  "createdAt": "2026-03-05T13:15:00Z",
  "data": {
    "attendee": {
      "id": "att_7g8h9i0j1k2l",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "ticketType": "general",
      "carbonOffset": {
        "opted": true,
        "amount": 25.00
      }
    },
    "event": {
      "id": "evt_1a2b3c4d5e6f",
      "name": "Sustainable Tech Summit 2026"
    }
  },
  "account": {
    "id": "acc_xyz789",
    "name": "GreenTech Events"
  }
}

sustainability.goal_achieved

{
  "id": "evt_delivery_789ghi",
  "type": "sustainability.goal_achieved",
  "createdAt": "2026-06-17T18:30:00Z",
  "data": {
    "event": {
      "id": "evt_1a2b3c4d5e6f",
      "name": "Sustainable Tech Summit 2026"
    },
    "goal": {
      "type": "carbon_neutral",
      "achieved": true,
      "metrics": {
        "totalEmissions": 45800,
        "totalOffset": 46200,
        "percentage": 100.9
      }
    }
  },
  "account": {
    "id": "acc_xyz789",
    "name": "GreenTech Events"
  }
}

Verifying Webhook Signatures

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

Verification Process

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

Example Implementation

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + 
    crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js example
app.post('/webhook-handler', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-ecoevents-signature'];
  const payload = req.body;
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  // Process webhook event
  
  res.status(200).send('OK');
});

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

error

object

Error details

Show properties

code

string

Error code (e.g., “INVALID_URL”, “INVALID_EVENT_TYPE”, “UNAUTHORIZED”)

message

string

Human-readable error message

details

object

Additional error context (optional)

Common Error Codes

Status Code	Error Code	Description
400	INVALID_REQUEST	Invalid request parameters
400	INVALID_URL	URL must use HTTPS protocol
400	INVALID_EVENT_TYPE	One or more event types are invalid
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Webhook not found
409	DUPLICATE_WEBHOOK	Webhook with this URL already exists
429	RATE_LIMIT_EXCEEDED	Too many requests
500	INTERNAL_ERROR	Server error

Overview

Endpoints

​Overview

​Authentication

​Create Webhook

POST /api/webhooks

​Request

​Response

​Example

​Response Example

​List Webhooks

GET /api/webhooks

​Query Parameters

​Response

​Example

​Delete Webhook

DELETE /api/webhooks/:id

​Path Parameters

​Response

​Example

​Event Types

​Available Event Types

​Event Events

​Attendee Events

​Sustainability Events

​Analytics Events

​Webhook Payload Structure

​Headers

​Payload

​Event Payload Examples

​event.created

​attendee.registered

​sustainability.goal_achieved

​Verifying Webhook Signatures

​Verification Process

​Example Implementation

​Best Practices

Use HTTPS

Verify Signatures

Respond Quickly

Process Async

​Retry Logic

​Idempotency

​Error Responses

​Common Error Codes

Build docs developers (and LLMs) love

Overview

Authentication

Create Webhook

Request

Response

Example

Response Example

List Webhooks

Query Parameters

Response

Example

Delete Webhook

Path Parameters

Response

Example

Event Types

Available Event Types

Event Events

Attendee Events

Sustainability Events

Analytics Events

Webhook Payload Structure

Headers

Payload

Event Payload Examples

event.created

attendee.registered

sustainability.goal_achieved

Verifying Webhook Signatures

Verification Process

Example Implementation

Best Practices

Retry Logic

Idempotency

Error Responses

Common Error Codes