API reference

Alerts and webhooks

Notification rules, the notification log and the account's webhook signing secret.

On this page

GET/v1/account/notifications/rules

The notification webhook and email, each rule with what it fired, and the low-balance alert.

Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.

No parameters.

GET /v1/account/notifications/rules

curl
curl https://api.usdf.fi/v1/account/notifications/rules \
  -H "Authorization: Bearer $SESSION"

PUT/v1/account/notifications/rules

The fields sent replace what they name; one left out is kept. rules replaces every rule ([] removes them all). Everything is checked before anything is written.

Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.

NameTypeRequiredDescription
webhook_urlstring or nullNoAn https URL on a public host; null removes it.
emailbooleanNoAlso email each notification to the sign-in's verified address, when the gateway sends email.
rulesarrayNokey_spend (key_id, percent), account_spend (period, threshold or threshold_units) and model_change rules; each takes enabled.
balance_lowobject or nullNothreshold: the low-balance alert in USDF; null removes it.

PUT /v1/account/notifications/rules

curl
curl -X PUT https://api.usdf.fi/v1/account/notifications/rules \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://example.com/usdf-hooks",
    "email": true,
    "rules": [
      {"kind": "key_spend", "key_id": null, "percent": 80},
      {"kind": "account_spend", "period": "day", "threshold": "25"},
      {"kind": "model_change"}
    ],
    "balance_low": {"threshold": "5"}
  }'

GET/v1/account/notifications

The account's notifications of the last 90 days, newest first, each with its data and what became of its webhook and its email.

Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.

NameTypeRequiredDescription
limitintegerNoQuery. How many notifications to return.
beforestringNoQuery. The page.next_before of the previous page.

GET /v1/account/notifications

curl
curl https://api.usdf.fi/v1/account/notifications \
  -H "Authorization: Bearer $SESSION"

POST/v1/account/notifications/test

One signed notification.test POST to the account's webhook, answered with what the receiver said.

Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.

No parameters.

POST /v1/account/notifications/test

curl
curl -X POST https://api.usdf.fi/v1/account/notifications/test \
  -H "Authorization: Bearer $SESSION"

Response, trimmed

{
  "object": "notification_test",
  "ok": true,
  "status": …,
  "error": null,
  "signed": true,
  "at": "<time>"
}

GET/v1/account/webhook-secret

The secret every delivery to a URL the account set is signed with (made now if there is none), when it was made and when it was last rotated.

Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.

No parameters.

GET /v1/account/webhook-secret

curl
curl https://api.usdf.fi/v1/account/webhook-secret \
  -H "Authorization: Bearer $SESSION"

Response, trimmed

{
  "object": "webhook_secret",
  "enabled": true,
  "secret": "whsec_…",
  "created_at": "<time>",
  "rotated_at": null,
  "header": "x-usdf-signature",
  "timestamp_header": "x-usdf-timestamp",
  "destination_header": "x-usdf-destination",
  "note": "…"
}

POST/v1/account/webhook-secret

A new secret. The old one stops signing at once.

Auth: Session, not an API key: Authorization: Bearer <session token>. See Sign in.

No parameters.

POST /v1/account/webhook-secret

curl
curl -X POST https://api.usdf.fi/v1/account/webhook-secret \
  -H "Authorization: Bearer $SESSION"
Foundry documentation

Confirm it's you

Confirm to continue the action you started.

Checking confirmation options…