> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodemaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get notified when something happens on your account instead of polling. Create a webhook, discover event types, and rotate the signing secret.

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](/proxy-api/overview).

## Find out which events exist

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

```bash theme={null}
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

```bash theme={null}
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

<Warning>
  **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.
</Warning>

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

```bash theme={null}
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`.

<Note>
  **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.
</Note>

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.

```bash theme={null}
curl https://api.nodemaven.com/api/v2/base/webhooks \
  -H "Authorization: x-api-key YOUR_API_KEY"
```

## Updating a webhook

<Warning>
  **`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.
</Warning>

## Turning one off

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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.