Webhooks

Create a webhook

Creates a webhook that sends the events you name to url. It belongs to your key, or your app's grant: Marfa deletes it when that is revoked, and sends nothing while it lacks webhooks.manage or the key has expired.

POST
/webhooks

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Header parameters

X-Marfa-Instance-Id?string

The ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.

Match^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

application/json
  1. body
url*string

The URL Marfa posts events to: http or https, with no user name or password. Unless the instance allows private addresses, it must reach a public address: Marfa refuses a URL whose host resolves to a private one, and checks again at each delivery.

Length1 <= length
events*array<>

The events to send. Name each one: there's no wildcard.

Items1 <= items
type_filter?|

Send item events only for this type and its subtypes, such as core.media, or for every type a pattern such as app.* matches. The type needn't be registered. Edge events aren't filtered. Leave it out, blank or null for every type.

secret?string

The key Marfa signs each delivery with. Leave it out for Marfa to generate one.

Length32 <= length

Response body

About errors

Returns the new webhook with its whole secret, which no other response shows. Use it to check each delivery's X-Marfa-Signature.

application/json
  1. response

A webhook sends the events you choose, as you can read them, to a URL.

id*string

Unique identifier for the webhook.

url*string

The URL Marfa posts events to.

events*array<string>

The events Marfa sends, such as item.created.

type_filter*|

The type, with its subtypes, or the pattern whose item events Marfa sends. null when Marfa sends item events of every type. Edge events aren't filtered.

secret*string

The key Marfa signs each delivery with. Only POST /webhooks returns it whole; other responses show **** and its last four characters.

active*boolean

true if Marfa sends events to the webhook.

created_at*string

When the webhook was created, in UTC.

updated_at*string

When the webhook last changed, in UTC.

  • validation_error: a field is invalid. For example, url isn't http or https, carries a user name or password, or names an IP address that isn't public; events is empty or names an unknown event or *; secret is too short; or type_filter is *, malformed or a list; or the body has a field this endpoint doesn't take.
  • missing_required_field: url or events is missing.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • forbidden: you don't have webhooks.manage.
application/json
  1. response

An error response.

error*

What went wrong.

request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.

application/json
  1. response

An error response.

error*

What went wrong.

  • conflict: You already hold 100 webhooks. Delete one, then register this one. details.reason is webhook_cap and details.cap is 100.
  • instance_changed: X-Marfa-Instance-Id names another instance. Nothing is written. Rebuild the working copy from the instance at this address.
application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

request_too_large: the request body is larger than this instance accepts.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X POST 'http://localhost:8600/webhooks' \  -H 'Content-Type: application/json' \  -d '{  "url": "string",  "events": [    "item.created"  ]}'
About errors
{  "id": "01a1011f-f8a6-7d27-8213-d126f553409e",  "url": "https://hooks.example.com/marfa",  "events": [    "item.created",    "item.updated"  ],  "type_filter": "acme.deal",  "secret": "b65d38b03fdd936af205fe4d2468727c8be397a5decde1bdf1e07e43e4c4deb0",  "active": true,  "created_at": "2026-10-03T09:56:05.889Z",  "updated_at": "2026-10-03T09:56:05.889Z"}