space.hooks.events

An event is one webhook a source received, kept as it arrived: its method, path, query, headers, and body. Each connection that took it made a delivery. An event is routed when at least one connection took it, and filtered when none did, because no enabled connection’s filter matched.

Events and their deliveries are kept for 30 days, then deleted. Every call below can also fail with the codes shared by all of space, such as missing_project, forbidden, timeout, or network_error. See SpaceError.

space.hooks.events.list()

Lists the project’s events, newest first, with a count of their deliveries by state. The list leaves out headers and bodies; read one event with get() for those.

space.hooks.events.list(filter?: {
  sourceId?: string
  status?: "routed" | "filtered"
  signal?: AbortSignal
  timeoutMs?: number
}): Paged<EventSummary>

filter.sourceIdstring

Only the events this source received.

filter.statusstring

routed for events at least one connection took, or filtered for events none took.

filter.signalAbortSignal

Cancels the call when it aborts. The promise then rejects with aborted.

filter.timeoutMsnumber

The longest each request may take, in milliseconds. The client’s timeoutMs when you leave it out, 30,000 by default.

Returns a Paged<EventSummary> at once, without a request. It reads the event summaries 200 at a time as you go: loop over it with for await, collect every one with .all(), or read one page with .page(cursor), which resolves to { items, nextCursor }.

sourceId and status are checked when the list is read, not when you call list(). A wrong one rejects the first read with validation_failed, and nothing is sent.

import { space } from "digitospace"

const events = space.hooks.events.list({
  sourceId: "01m3m5gpkrvj4qdxwkde3vt4w9",
  status: "filtered",
})

for await (const event of events) {
  console.log(event.receivedAt, event.method, event.path, event.bodySize)
}

space.hooks.events.get()

Reads one event, with its headers, its body, and every delivery it made.

space.hooks.events.get(
  event: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<HookEvent>

eventstringRequired

The event’s ID, 26 lowercase letters and digits. It is also the webhook-id header on every delivery of the event.

options.signalAbortSignal

Cancels the call when it aborts.

options.timeoutMsnumber

The longest each request may take, in milliseconds.

Returns a promise of the event.

import { space } from "digitospace"

const event = await space.hooks.events.get("01m3my2b42vahrbx8zt4fw84wc")

if (event.bodyEncoding === "text") {
  const payment = JSON.parse(event.body) as { reference: string; amount: number }
  console.log(payment.reference, payment.amount)
}

for (const delivery of event.deliveryList) {
  console.log(delivery.destinationId, delivery.status)
}