Webhooks

A webhook tells your own system when something happens on your NodeMaven account, so you do not have to poll the API to find out. You give NodeMaven a URL, choose which events you care about, and we send a request to that URL when one of them occurs. All webhook endpoints sit under the base URL and use the same API key as the rest of the NodeMaven API.

Find out which events exist

The list of available events is returned by the API, so it stays current as events are added.

curl https://api.nodemaven.com/api/v2/base/webhooks/event-types \
  -H "Authorization: x-api-key YOUR_API_KEY"

Each entry describes one event:

Field	What it is
`type`	The identifier you put in the `events` array when creating a webhook
`category`	The grouping the event belongs to
`description`	What the event means

Call this first. The events values you send when creating a webhook come from this list.

Create a webhook

curl -X POST https://api.nodemaven.com/api/v2/base/webhooks \
  -H "Authorization: x-api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/nodemaven",
    "events": ["EVENT_TYPE"],
    "description": "Production alerting"
  }'

Field	Required	Notes
`url`	Yes	Where we send the request. Maximum 500 characters
`events`	Yes	Array of event `type` values from the event-types endpoint
`description`	No	Free text to help you tell webhooks apart. Maximum 200 characters. Defaults to empty
`enabled`	No	Defaults to `true`. Set `false` to create it switched off

The secret is shown once

The creation response is the only time you see the signing secret.POST /webhooks returns a secret field. Listing or fetching a webhook afterwards does not include it. If you do not store it when you create the webhook, your only route back is to rotate it.

The secret is what lets you confirm an incoming request really came from NodeMaven rather than from someone who guessed your URL. Store it somewhere your receiving service can read it, and treat it like any other credential.

Rotating the secret

curl -X POST https://api.nodemaven.com/api/v2/base/webhooks/WEBHOOK_ID/rotate-secret \
  -H "Authorization: x-api-key YOUR_API_KEY"

The response returns the new secret and, importantly, previous_secret_valid_until.

Rotation is not instant cut-over. previous_secret_valid_until is a timestamp telling you how long the old secret keeps working. Until it passes, requests may be signed with either secret, so your receiver should accept both during that window.If the field comes back null, the old secret is not retained and the change takes effect immediately.

That overlap is what lets you rotate without dropping deliveries. Deploy the new secret, wait for the window to pass, then stop accepting the old one.

Checking whether a webhook is working

Every webhook carries a last_delivery object, so you can see what happened on the most recent attempt without adding your own logging.

Field	What it tells you
`at`	When the last delivery was attempted
`status`	The outcome of that attempt
`response_code`	The HTTP status your endpoint returned. May be `null` if we never got a response

A response_code of null usually means your endpoint could not be reached at all, rather than that it rejected the request.

curl https://api.nodemaven.com/api/v2/base/webhooks \
  -H "Authorization: x-api-key YOUR_API_KEY"

Updating a webhook

PUT /webhooks/{id} is a full replacement, not a patch. Any field you leave out reverts to its default rather than keeping its current value, so description becomes empty and enabled becomes true.Send the complete object every time, including the fields you are not changing.

Turning one off

To stop deliveries without losing the configuration, update the webhook with enabled set to false. To remove it permanently, delete it:

curl -X DELETE https://api.nodemaven.com/api/v2/base/webhooks/WEBHOOK_ID \
  -H "Authorization: x-api-key YOUR_API_KEY"

Deleting is irreversible. The signing secret goes with it, so a replacement webhook gets a new one.

Platform API

Product APIs

Find out which events exist

Create a webhook

The secret is shown once

Rotating the secret

Checking whether a webhook is working

Updating a webhook

Turning one off

​Find out which events exist

​Create a webhook

​The secret is shown once

​Rotating the secret

​Checking whether a webhook is working

​Updating a webhook

​Turning one off

Find out which events exist

Create a webhook

The secret is shown once

Rotating the secret

Checking whether a webhook is working

Updating a webhook

Turning one off