Webhooks

Update a webhook

Updates a webhook and returns it. Fields you leave out keep their values. Marfa cancels a pending delivery if you change url, set active to false, or change events or type_filter to exclude it. To change the secret, create a new webhook.

PATCH
/webhooks/{id}

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path parameters

id*string

The ID of the webhook.

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.

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. Blank or null removes it.

active?boolean

false stops sending events and cancels pending deliveries. true starts again.

Response body

About errors

Returns the updated webhook.

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 *; or type_filter is *, malformed or a list; or the body has a field this endpoint doesn't take.
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.

  • webhook_not_found: no webhook of yours has this ID.
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.

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