MetorialDocs

Callbacks

A callback is what receives provider events for an integration provider. Creating one enables callbacks on the integration provider, and Metorial then registers the callback against every matching integration instance. Setting `callbacks.status` on the integration provider itself does the same thing.

The Callback object

callback.json
{
  "object": "callback",
  "id": "cbk_4dEfGhJkLmNpQrSt",
  "status": "active",
  "name": "Production GitHub Events",
  "description": "Repository events for the production workspace",
  "metadata": {},
  "integration_id": "int_2bCdEfGhJkLmNpQr",
  "integration_provider_id": "inp_3cDeFgHjKlMnPqRs",
  "provider": {
    "object": "provider#preview",
    "id": "pro_5gHjKlMnPqRsTuVw",
    "name": "GitHub",
    "description": "Connect to GitHub repositories, issues, and pull requests",
    "slug": "github",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"callback"required
idstringrequired
status"active" | "archived" | "deleted"required
namestringrequired
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
integration_idstringrequired
integration_provider_idstringrequired
created_atdaterequired
updated_atdaterequired

Endpoints

List callbacks

GET/callbacks

Returns a paginated list of callbacks.

Query parameters

idstring or string[]optional

Filter by callback ID(s)

integration_idstring or string[]optional

Filter by integration ID(s)

integration_provider_idstring or string[]optional

Filter by integration provider ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

status"active" | "archived" | "deleted" or "active" | "archived" | "deleted"[]optional

Filter by callback lifecycle status

Example request

curl -X GET "https://api.metorial.com/callbacks" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Create callback

POST/callbacks

Enables callbacks for an integration provider and returns the callback it created. Only providers whose type reports `triggers.status` as `enabled` support this. Callback instances are then registered for every matching integration instance in the background.

Request body

integration_idstringrequired

Integration the integration provider belongs to

integration_provider_idstringrequired

Integration provider to enable callbacks for

namestringoptional

Display name for the callback. Defaults to the name of the integration provider.

descriptionstringoptionalnullable

Description for the callback. Defaults to the description of the integration provider.

Example request

curl -X POST "https://api.metorial.com/callbacks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "integration_id": "int_2bCdEfGhJkLmNpQr",
  "integration_provider_id": "inp_3cDeFgHjKlMnPqRs",
  "name": "Production GitHub Events",
  "description": "Repository events for the production workspace"
}'

Get callback

GET/callbacks/:callback_id

Retrieves a specific callback by ID.

Path parameters

callback_idstringrequired

The unique identifier for the callback

Example request

curl -X GET "https://api.metorial.com/callbacks/cal_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."

Update callback

PATCH/callbacks/:callback_id

Updates the name, description or metadata of a callback. Everything else about a callback is derived from its integration provider - set `callbacks.status` to `disabled` there to tear it down.

Path parameters

callback_idstringrequired

The unique identifier for the callback

Request body

namestringoptional

Updated display name

descriptionstringoptionalnullable

Updated description

metadataRecord<string, any>optionalnullable

Updated custom metadata

Example request

curl -X PATCH "https://api.metorial.com/callbacks/cal_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "Staging GitHub Events",
  "description": "Repository events for the staging workspace",
  "metadata": {}
}'

Delete callback

DELETE/callbacks/:callback_id

Disables callbacks on the underlying integration provider, tearing down this callback and every callback instance registered for it.

Path parameters

callback_idstringrequired

The unique identifier for the callback

Example request

curl -X DELETE "https://api.metorial.com/callbacks/cal_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."