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 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.
| Name | Type | Required | Description |
|---|---|---|---|
webhook_ | string or null | No | An https URL on a public host; null removes it. |
email | boolean | No | Also email each notification to the sign-in's verified address, when the gateway sends email. |
rules | array | No | key_spend (key_id, percent), account_spend (period, threshold or threshold_units) and model_change rules; each takes enabled. |
balance_ | object or null | No | threshold: the low-balance alert in USDF; null removes it. |
PUT /v1/account/notifications/rules
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.
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Query. How many notifications to return. |
before | string | No | Query. The page.next_before of the previous page. |
GET /v1/account/notifications
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 -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 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 -X POST https://api.usdf.fi/v1/account/webhook-secret \
-H "Authorization: Bearer $SESSION"