Events API

Events are webhook payloads received by sources.

Endpoints

Method	Path	Description
GET	`/api/events`	List events
GET	`/api/events/{id}`	Get event
GET	`/api/events/{id}/payload`	Get raw payload
GET	`/api/events/{id}/deliveries`	Get deliveries for event
POST	`/api/events/{id}/replay`	Replay event
DELETE	`/api/events/{id}`	Delete event

Event Object

json

{
  "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...",
  "signatureValid": true,
  "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

http

GET /api/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
signatureValid	boolean	Filter by signature validation result

Example

curlJavaScriptPython

bash

curl "https://api.hookbase.app/api/events?sourceId=src_xyz&status=failed" \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/events?sourceId=src_xyz&status=failed', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const { data } = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/events?sourceId=src_xyz&status=failed',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()['data']

Response

json

{
  "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

http

GET /api/events/{id}

Query Parameters

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

Example

curlJavaScriptPython

bash

curl "https://api.hookbase.app/api/events/evt_abc123?includePayload=true&includeDeliveries=true" \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/events/evt_abc123?includePayload=true&includeDeliveries=true', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const data = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/events/evt_abc123?includePayload=true&includeDeliveries=true',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

Response

json

{
  "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:

http

POST /api/events/{id}/replay

Request Body (Optional)

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

Example

curlJavaScriptPython

bash

# Replay to all destinations
curl -X POST https://api.hookbase.app/api/events/evt_abc123/replay \
  -H "Authorization: Bearer whr_your_api_key"

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

javascript

// Replay to all destinations
const response = await fetch('https://api.hookbase.app/api/events/evt_abc123/replay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const { data } = await response.json();

// Replay to specific destinations
const response2 = await fetch('https://api.hookbase.app/api/events/evt_abc123/replay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destinationIds: ['dst_slack1']
  })
});
const { data: data2 } = await response2.json();

python

import requests

# Replay to all destinations
response = requests.post(
  'https://api.hookbase.app/api/events/evt_abc123/replay',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()

# Replay to specific destinations
response2 = requests.post(
  'https://api.hookbase.app/api/events/evt_abc123/replay',
  headers={'Authorization': 'Bearer whr_your_api_key'},
  json={'destinationIds': ['dst_slack1']}
)
data2 = response2.json()

Response

json

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

Delete Event

http

DELETE /api/events/{id}

WARNING

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

Example

curlJavaScriptPython

bash

curl -X DELETE https://api.hookbase.app/api/events/evt_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/events/evt_abc123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});

python

import requests

response = requests.delete(
  'https://api.hookbase.app/api/events/evt_abc123',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)

Response

204 No Content

Event Deliveries

Get all deliveries for a specific event.

http

GET /api/events/{id}/deliveries

Query Parameters

Parameter	Type	Description
status	string	Filter by delivery status

Example

curlJavaScriptPython

bash

curl https://api.hookbase.app/api/events/evt_abc123/deliveries \
  -H "Authorization: Bearer whr_your_api_key"

javascript

const response = await fetch('https://api.hookbase.app/api/events/evt_abc123/deliveries', {
  headers: {
    'Authorization': 'Bearer whr_your_api_key'
  }
});
const { data } = await response.json();

python

import requests

response = requests.get(
  'https://api.hookbase.app/api/events/evt_abc123/deliveries',
  headers={'Authorization': 'Bearer whr_your_api_key'}
)
data = response.json()['data']

Response

json

{
  "data": [
    {
      "id": "dlv_111",
      "destinationId": "dst_slack1",
      "destinationName": "Slack #dev",
      "status": "delivered",
      "attemptCount": 1,
      "latency": 245,
      "statusCode": 200,
      "deliveredAt": "2024-01-15T10:30:01Z"
    },
    {
      "id": "dlv_222",
      "destinationId": "dst_api",
      "destinationName": "Production API",
      "status": "failed",
      "attemptCount": 5,
      "latency": null,
      "statusCode": 500,
      "error": "Internal Server Error",
      "deliveredAt": null
    }
  ]
}

Event Payload

Get just the event payload:

http

GET /api/events/{id}/payload

Response

Returns the raw payload as received:

json

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

Event Timeline

Get detailed timing information:

http

GET /api/events/{id}/timeline

Response

json

{
  "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

http

POST /api/events/bulk/replay

Request Body

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

Example

curlJavaScriptPython

bash

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

javascript

const response = await fetch('https://api.hookbase.app/api/events/bulk/replay', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    eventIds: ['evt_1', 'evt_2', 'evt_3']
  })
});
const { data } = await response.json();

python

import requests

response = requests.post(
  'https://api.hookbase.app/api/events/bulk/replay',
  headers={'Authorization': 'Bearer whr_your_api_key'},
  json={'eventIds': ['evt_1', 'evt_2', 'evt_3']}
)
data = response.json()

Response

json

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

Error Responses

404 Not Found

Event not found:

json

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

410 Gone

Event payload expired (retention policy):

json

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

Events API ​

Endpoints ​

Event Object ​

Status Values ​

List Events ​

Query Parameters ​

Example ​

Response ​

Get Event ​

Query Parameters ​

Example ​

Response ​

Replay Event ​

Request Body (Optional) ​

Example ​

Response ​

Delete Event ​

Example ​

Response ​

Event Deliveries ​

Query Parameters ​

Example ​

Response ​

Event Payload ​

Response ​

Event Timeline ​

Response ​

Bulk Operations ​

Bulk Replay ​

Request Body ​

Example ​

Response ​

Error Responses ​

404 Not Found ​

410 Gone ​

Events API

Endpoints

Event Object

Status Values

List Events

Query Parameters

Example

Response

Get Event

Query Parameters

Example

Response

Replay Event

Request Body (Optional)

Example

Response

Delete Event

Example

Response

Event Deliveries

Query Parameters

Example

Response

Event Payload

Response

Event Timeline

Response

Bulk Operations

Bulk Replay

Request Body

Example

Response

Error Responses

404 Not Found

410 Gone