Events API

Events are webhook payloads received by sources.

Endpoints

Method	Path	Description
GET	/api/organizations/{orgId}/events	List events
GET	/api/organizations/{orgId}/events/{id}	Get event
POST	/api/organizations/{orgId}/events/{id}/replay	Replay event
DELETE	/api/organizations/{orgId}/events/{id}	Delete event

Event Object

{
  "id": "evt_abc123",
  "sourceId": "src_xyz789",
  "source": {
    "id": "src_xyz789",
    "name": "GitHub"
  },
  "status": "delivered",
  "headers": {
    "Content-Type": "application/json",
    "X-GitHub-Event": "push",
    "X-GitHub-Delivery": "72d3162e-cc78-11e3-81ab-4c9367dc0958"
  },
  "payloadSize": 2456,
  "payloadHash": "sha256:abc123...",
  "deliveriesCount": 2,
  "deliveriesSucceeded": 2,
  "deliveriesFailed": 0,
  "receivedAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

Status Values

Status	Description
pending	Awaiting delivery
delivered	All deliveries succeeded
partial	Some deliveries failed
failed	All deliveries failed

List Events

GET /api/organizations/{orgId}/events

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)
sourceId	string	Filter by source
status	string	Filter by status
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)
search	string	Search in payload

Example

curl "https://api.webhookrelay.com/api/organizations/org_123/events?sourceId=src_xyz&status=failed" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "data": [
    {
      "id": "evt_abc123",
      "sourceId": "src_xyz789",
      "status": "delivered",
      "headers": {
        "X-GitHub-Event": "push"
      },
      "payloadSize": 2456,
      "deliveriesCount": 2,
      "deliveriesSucceeded": 2,
      "receivedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1523,
    "page": 1,
    "pageSize": 20
  }
}

Get Event

GET /api/organizations/{orgId}/events/{id}

Query Parameters

Parameter	Type	Description
includePayload	boolean	Include full payload (default: false)
includeDeliveries	boolean	Include delivery details (default: false)

Example

curl "https://api.webhookrelay.com/api/organizations/org_123/events/evt_abc123?includePayload=true&includeDeliveries=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "id": "evt_abc123",
  "sourceId": "src_xyz789",
  "source": {
    "id": "src_xyz789",
    "name": "GitHub"
  },
  "status": "delivered",
  "headers": {
    "Content-Type": "application/json",
    "X-GitHub-Event": "push",
    "X-GitHub-Delivery": "72d3162e-cc78-11e3-81ab-4c9367dc0958"
  },
  "payload": {
    "ref": "refs/heads/main",
    "repository": {
      "full_name": "user/repo"
    },
    "pusher": {
      "name": "user"
    }
  },
  "payloadSize": 2456,
  "deliveries": [
    {
      "id": "dlv_111",
      "destinationId": "dst_slack1",
      "status": "delivered",
      "attemptCount": 1,
      "latency": 245,
      "deliveredAt": "2024-01-15T10:30:01Z"
    },
    {
      "id": "dlv_222",
      "destinationId": "dst_api",
      "status": "delivered",
      "attemptCount": 1,
      "latency": 180,
      "deliveredAt": "2024-01-15T10:30:01Z"
    }
  ],
  "receivedAt": "2024-01-15T10:30:00Z"
}

Replay Event

Re-deliver an event to all destinations:

POST /api/organizations/{orgId}/events/{id}/replay

Request Body (Optional)

Field	Type	Description
destinationIds	string[]	Specific destinations (default: all)

Example

# Replay to all destinations
curl -X POST https://api.webhookrelay.com/api/organizations/org_123/events/evt_abc123/replay \
  -H "Authorization: Bearer YOUR_TOKEN"

# Replay to specific destinations
curl -X POST https://api.webhookrelay.com/api/organizations/org_123/events/evt_abc123/replay \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destinationIds": ["dst_slack1"]}'

Response

{
  "message": "Event queued for replay",
  "deliveriesCreated": 2
}

Delete Event

DELETE /api/organizations/{orgId}/events/{id}

WARNING

Deleting an event also deletes all associated deliveries and the stored payload.

Example

curl -X DELETE https://api.webhookrelay.com/api/organizations/org_123/events/evt_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

204 No Content

Event Payload

Get just the event payload:

GET /api/organizations/{orgId}/events/{id}/payload

Response

Returns the raw payload as received:

{
  "ref": "refs/heads/main",
  "repository": {
    "full_name": "user/repo"
  },
  "commits": [...]
}

Event Timeline

Get detailed timing information:

GET /api/organizations/{orgId}/events/{id}/timeline

Response

{
  "received": "2024-01-15T10:30:00.000Z",
  "validated": "2024-01-15T10:30:00.005Z",
  "queued": "2024-01-15T10:30:00.010Z",
  "deliveries": [
    {
      "destinationId": "dst_slack1",
      "destinationName": "Slack #dev",
      "attempts": [
        {
          "attemptNumber": 1,
          "startedAt": "2024-01-15T10:30:00.015Z",
          "completedAt": "2024-01-15T10:30:00.260Z",
          "status": "success",
          "statusCode": 200,
          "latency": 245
        }
      ]
    }
  ],
  "totalDuration": 260
}

Bulk Operations

Bulk Replay

POST /api/organizations/{orgId}/events/bulk/replay

Request Body

Field	Type	Description
eventIds	string[]	Event IDs to replay
destinationIds	string[]	Specific destinations (optional)

Example

curl -X POST https://api.webhookrelay.com/api/organizations/org_123/events/bulk/replay \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventIds": ["evt_1", "evt_2", "evt_3"]
  }'

Response

{
  "message": "Events queued for replay",
  "eventsQueued": 3,
  "deliveriesCreated": 6
}

Error Responses

404 Not Found

Event not found:

{
  "error": "Not Found",
  "message": "Event with ID evt_xyz not found",
  "code": "RESOURCE_NOT_FOUND"
}

410 Gone

Event payload expired (retention policy):

{
  "error": "Gone",
  "message": "Event payload has been deleted due to retention policy",
  "code": "PAYLOAD_EXPIRED"
}