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

# Signatures and delivery

> How Coinversa Pulse signs and delivers webhooks — Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature), v1 HMAC-SHA256 over id.timestamp.body, one signing secret per subscription readable over the API, a known-answer test vector, the standardwebhooks libraries for Node, Python and Go, acknowledgement, retries, 410 and the transport rules.

Every delivery is a signed `POST` of one frame, signed the **[Standard Webhooks](https://www.standardwebhooks.com)** way — an open specification with verifiers for most languages, so an off-the-shelf `standardwebhooks` library verifies it in three lines. Verify the signature, deduplicate on `webhook-id`, answer `2xx`, and do the real work after you answer.

## The request

```http theme={null}
POST /hooks/coinversa HTTP/1.1
Content-Type: application/json
webhook-id: …
webhook-timestamp: 1762179668
webhook-signature: v1,Hn1Yv8m2dQ4pX0k7Jf3sR9tW6bL5cE1aZ8uN2yG4oPs=
```

| Header | Meaning |
| - | - |
| `webhook-id` | The delivery's id, stable across retries of the same delivery. **Your idempotency key** |
| `webhook-timestamp` | Unix seconds when this attempt was signed |
| `webhook-signature` | `v1,<base64>` — the HMAC-SHA256 below |

The body is the [delivered frame](https://docs.coinversa.ai/webhooks/events.md#the-delivered-frame): the raw source frame plus `subscriptionId`. Route on `subscriptionId` — the `channel` alone does not tell two subscriptions of the same type apart.

## What is signed

```text theme={null}
signed_content = webhook-id + "." + webhook-timestamp + "." + raw_body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
```

* `key` comes from the subscription's signing secret, the `whsec_…` value returned when you created it. Hand that string, as you received it, to a Standard Webhooks library: the library handles the key, so you do not compute the HMAC yourself.
* `raw_body` is the request body **exactly as received**. Read it as bytes before any JSON parser touches it — parsing and re-serialising changes the bytes and the signature will not match.

A request is authentic when `webhook-signature` equals the signature you computed, compared in **constant time**, and `webhook-timestamp` is close to your clock — the libraries enforce a five-minute tolerance by default. Keep that check: it is what stops a captured delivery from being replayed at you later.

### Known-answer test vector

Check your verifier against these exact Standard Webhooks inputs before you point it at live traffic. The timestamp is in 2023, so a verifier that enforces the tolerance against the real clock will reject it — pass a fixed "now" of `1700000000` in your test.

| Input | Value |
| - | - |
| Secret | `whsec_MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTI=` |
| `webhook-id` | `msg_p5jXN8AQM9LWL0o4reCVkeDbYk` |
| `webhook-timestamp` | `1700000000` |
| Body | `{"ok":true}` |
| Signed content | `msg_p5jXN8AQM9LWL0o4reCVkeDbYk.1700000000.{"ok":true}` |
| **`webhook-signature`** | **`v1,L3ItB2kRQK8HKNbwA+otrQh1dHwBG7Oe8kEGy3vmr8g=`** |

## Verify with a library

The Standard Webhooks project publishes verifiers for most languages. Each takes the full `whsec_…` secret, the raw body and the request headers, checks the timestamp tolerance and the `v1` signature, and throws or returns an error on a mismatch.

```javascript Node theme={null}
// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.COINVERSA_WEBHOOK_SECRET); // "whsec_…"

export function verifyCoinversaWebhook(rawBody, headers) {
  // headers: an object with lowercase keys, e.g. Express req.headers
  // Returns the parsed frame, or throws WebhookVerificationError.
  return wh.verify(rawBody, {
    "webhook-id": headers["webhook-id"],
    "webhook-timestamp": headers["webhook-timestamp"],
    "webhook-signature": headers["webhook-signature"],
  });
}
```

```python Python theme={null}
# pip install standardwebhooks
import os
from typing import Optional

from standardwebhooks.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["COINVERSA_WEBHOOK_SECRET"])  # "whsec_…"


def verify_coinversa_webhook(raw_body: bytes, headers: dict) -> Optional[dict]:
    try:
        return wh.verify(raw_body, headers)  # the parsed frame
    except WebhookVerificationError:
        return None
```

```go Go theme={null}
// go get github.com/standard-webhooks/standard-webhooks/libraries/go
package webhooks

import (
	"net/http"

	standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)

func NewVerifier(secret string) (*standardwebhooks.Webhook, error) {
	return standardwebhooks.NewWebhook(secret) // "whsec_…"
}

// VerifyCoinversaWebhook returns nil when the request is authentic.
func VerifyCoinversaWebhook(wh *standardwebhooks.Webhook, rawBody []byte, h http.Header) error {
	return wh.Verify(rawBody, h)
}
```

Hand the library the raw bytes: `express.raw({ type: "application/json" })` on the webhook route in Express (as in the [quickstart](https://docs.coinversa.ai/webhooks/quickstart.md#3-receive-and-verify-a-delivery)), `await request.body()` in FastAPI/Starlette, `request.get_data()` in Flask, `io.ReadAll(r.Body)` in Go.

Reject the request with a `4xx` when verification fails and never log the secret.

## One secret per subscription

Each subscription has **its own** signing secret, generated when it is created and returned in the create response only. Read it again at any time with `GET /v1/subscriptions/{id}/secret` ([reference](https://docs.coinversa.ai/webhooks/api.md#read-the-signing-secret)); it is never in list responses. There is no rotation: a subscription's secret lives as long as the subscription does. To change it, delete the subscription and create it again — the new one gets a new secret.

If one receiver serves several subscriptions, look up the secret by the body's `subscriptionId` — or, simpler, give each subscription its own URL path.

An [inbox](https://docs.coinversa.ai/webhooks/inbox.md) subscription has **no** secret: nothing is POSTed, so nothing is signed, and `GET /v1/subscriptions/{id}/secret` answers `400` for it. You read its messages over the authenticated API instead of verifying them.

## Acknowledgement and retries

A delivery **succeeds** on any **2xx**. Anything else — another status, a timeout, a refused connection — is a failure and is retried on a bounded back-off, up to **nine attempts over about 76 hours**. A `Retry-After` header on your response is respected, up to 24 hours. When the attempts run out the delivery is dropped.

Two things follow from how retries are kept:

* Ordinary deliveries and their retries live **in memory**. A restart of the service loses them, and nothing is replayed — see [no delivery after a restart](https://docs.coinversa.ai/webhooks/troubleshooting.md#nothing-arrived-and-the-service-restarted). Only `priceCross`, cohort bias and liquidation risk deliveries use a durable outbox that survives restarts.
* The queue is **bounded**: 128 fresh deliveries plus 128 waiting retries across all subscriptions, each at most 1 MiB, and at most 16 slots for any one subscription across both pools. A retry waits in its own pool, so a failing receiver's back-off never holds a slot a fresh delivery could use; when a pool is full, further retries are dropped and logged, and a saturated subscription drops its own frames without taking another subscription's share. The numbers are on [Plan limits](https://docs.coinversa.ai/webhooks/limits.md#queues-and-the-outbox).

Delivery is **at least once**, and order across workers and retries is **not guaranteed**: a retry can arrive after a newer frame. Deduplicate on `webhook-id` and order by `seq` within one source if order matters.

## 410 disables the subscription

A **`410 Gone`** response disables the subscription at once: deliveries stop and it shows `disabled: true` in `GET /v1/subscriptions`. Frames matched while it is disabled are not kept. Re-enable it with `POST /v1/subscriptions/{id}/enable`, which is idempotent and answers `429` if the account is already at its subscription allowance — a disabled subscription does not count toward the allowance, so enabling one can put you over it. Return `410` only when you mean to stop the subscription.

## Transport rules

* **Public HTTPS on port 443.** Nothing else is accepted when you create the subscription.
* **No redirects.** A `3xx` is refused; register the final URL.
* **No private or reserved addresses.** Loopback, private, link-local and similar ranges are refused at creation.
* Answer first, then process: push the frame onto your own queue and return `200`. There is no replay, so a slow handler that times out costs you a retry at best and a dropped delivery at worst.


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