space.hooks.sources

Create, read, list, rename, and delete sources, the addresses that receive webhooks.

A source is an address that receives webhooks from any sender, such as a mobile money provider or a shop platform. Every request sent to its URL, with any method and any path after it, is kept as an event and sent on through the source’s connections. The body can be up to 5 MB. The sender gets 200 once the webhook is kept, so nothing it sends is lost, even when a destination is down.

We do not check the sender’s signature. The source URL is the secret, so keep it private and reset it if it leaks. The sender’s own signature headers are passed on unchanged with the same body, so a destination can still check them.

A project holds at most 100 sources. 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.sources.create()

Creates a source and gives it a URL.

space.hooks.sources.create(
  name: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Source>

namestringRequired: 1 to 100 characters after trimming, without line breaks or other control characters. Unique in the project.
options.signalAbortSignal: Cancels the call when it aborts. The promise then rejects with aborted.
options.timeoutMsnumber: The longest each request may take, in milliseconds. The client’s timeoutMs when you leave it out, 30,000 by default.

Returns a promise of the new source. Give its url to the sender. create() is not sent again after a network failure or a timeout, because the source may already exist.

Code	When
`validation_failed`	The name is empty, longer than 100 characters, or holds a line break. Nothing is sent
`hooks_name_taken`	Another source in the project has that name
`hooks_limit_reached`	The project already holds 100 sources

create-source.ts

import { space } from "digitospace"

const source = await space.hooks.sources.create("M-Pesa payments")

console.log(`Set the callback URL to ${source.url}`)

space.hooks.sources.get()

Reads one source.

space.hooks.sources.get(
  source: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Source>

sourcestringRequired: The source’s ID, 26 lowercase letters and digits.
options.signalAbortSignal: Cancels the call when it aborts.
options.timeoutMsnumber: The longest each request may take, in milliseconds.

Returns a promise of the source.

Code	When
`validation_failed`	The ID is not 26 lowercase letters and digits. Nothing is sent
`not_found`	The project has no source with that ID

get-source.ts

import { space } from "digitospace"

const source = await space.hooks.sources.get("01m3m5gpkrvj4qdxwkde3vt4w9")

console.log(source.name, source.url)

space.hooks.sources.list()

Lists the project’s sources, newest first.

space.hooks.sources.list(options?: {
  signal?: AbortSignal
  timeoutMs?: number
}): Paged<Source>

options.signalAbortSignal: Cancels the call when it aborts.
options.timeoutMsnumber: The longest each request may take, in milliseconds.

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

list-sources.ts

import { space } from "digitospace"

for await (const source of space.hooks.sources.list()) {
  console.log(source.name, source.url)
}

space.hooks.sources.rename()

Gives a source a new name. Its URL stays the same.

space.hooks.sources.rename(
  source: string,
  name: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Source>

sourcestringRequired: The source’s ID.
namestringRequired: 1 to 100 characters after trimming, without line breaks or other control characters. Unique in the project.
options.signalAbortSignal: Cancels the call when it aborts.
options.timeoutMsnumber: The longest each request may take, in milliseconds.

Returns a promise of the renamed source.

Code	When
`validation_failed`	The ID or the name breaks a rule above. Nothing is sent
`not_found`	The project has no source with that ID
`hooks_name_taken`	Another source in the project has that name

rename-source.ts

import { space } from "digitospace"

await space.hooks.sources.rename(
  "01m3m5gpkrvj4qdxwkde3vt4w9",
  "M-Pesa payments, Dar es Salaam"
)

space.hooks.sources.resetUrl()

Gives a source a new URL. Webhooks sent to the old URL are no longer kept, and the sender is not told, so give the new URL to every sender that uses the source.

space.hooks.sources.resetUrl(
  source: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<Source>

sourcestringRequired: The source’s ID.
options.signalAbortSignal: Cancels the call when it aborts.
options.timeoutMsnumber: The longest each request may take, in milliseconds.

Returns a promise of the source with its new url. It is not sent again after a network failure or a timeout, because the URL may already have changed.

Code	When
`validation_failed`	The ID is not 26 lowercase letters and digits. Nothing is sent
`not_found`	The project has no source with that ID

reset-source-url.ts

import { space } from "digitospace"

const source = await space.hooks.sources.resetUrl("01m3m5gpkrvj4qdxwkde3vt4w9")

console.log(`Give the sender the new URL: ${source.url}`)

space.hooks.sources.delete()

Deletes a source, with its connections and every event it received, and their deliveries. Webhooks sent to its URL afterwards are not kept. This cannot be undone.

space.hooks.sources.delete(
  source: string,
  options?: {
    signal?: AbortSignal
    timeoutMs?: number
  }
): Promise<void>

sourcestringRequired: The source’s ID.
options.signalAbortSignal: Cancels the call when it aborts.
options.timeoutMsnumber: The longest each request may take, in milliseconds.

Returns a promise that resolves when the source is gone.

Code	When
`validation_failed`	The ID is not 26 lowercase letters and digits. Nothing is sent
`not_found`	The project has no source with that ID

delete-source.ts

import { space } from "digitospace"

await space.hooks.sources.delete("01m3m5gpkrvj4qdxwkde3vt4w9")

Last updated 30 September 2026