API reference · Webhooks

Create a webhook endpoint

POSThttps://fomodata.dev/v1/webhooks

Scopes:webhooks:writeRate class:standardFlag:WEBHOOKS_ENABLED

Webhooks belong to the key's project and environment: a test key manages test-mode endpoints (sandbox events), a live key live endpoints.

The signing secret (whsec_…) is returned ONCE in this response. Every delivery carries FomoData-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>; reject timestamps older than 300 s. Failed deliveries retry after 1 min, 5 min, 30 min, 2 h and 12 h (6 attempts).

Example request

curl -X POST 'https://fomodata.dev/v1/webhooks' \
  -H "Authorization: Bearer $FOMODATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/fomodata",
  "events": [
    "thesis.created"
  ],
  "description": "Race entries"
}'

Try it in the playground

Request body

application/jsonCreateWebhookRequest

urlstringrequiredPublic https endpoint. Private, loopback, link-local and metadata addresses are refused.
eventsarray<EventType>required
filtersWebhookFilters & any+ 3 child attributes
- tokenarray<string>Token refs ($SYMBOL, address or tk_ id).
- handlearray<string>
- chainarray<string>
descriptionstring | null

Example bodyJSON

{
  "url": "https://example.com/hooks/fomodata",
  "events": [
    "thesis.created"
  ],
  "description": "Race entries"
}

Response

201 Created — includes the secret once

application/jsonWebhookWithSecret

objectenumrequired"webhook"
idstringrequired
urlstring (uri)required
descriptionstring | nullrequired
eventsarray<EventType>required
filtersobjectrequired+ 3 child attributes
- tokenarray<string>Token refs ($SYMBOL, address or tk_ id).
- handlearray<string>
- chainarray<string>
statusenumrequired"enabled""disabled""disabled_failing"
secret_prefixstringrequired
livemodebooleanrequired
created_atstring (date-time)required
updated_atstring (date-time)required
secretstringrequiredSigning secret — shown ONLY in the create/rotate response.

201 · exampleJSON

{
  "object": "webhook",
  "id": "wh_8Tq3NkVz1LmB5xRc7pYd2F",
  "url": "https://example.com",
  "description": "string",
  "events": [
    "thesis.created"
  ],
  "filters": {
    "token": [
      "string"
    ],
    "handle": [
      "string"
    ],
    "chain": [
      "string"
    ]
  },
  "status": "enabled",
  "secret_prefix": "whsec_Ab12",
  "livemode": true,
  "created_at": "2026-10-07T10:04:12.000Z",
  "updated_at": "2026-10-07T10:04:12.000Z",
  "secret": "string"
}

Errors

Status	When
`400`	Bad request
`401`	Missing, invalid, revoked or expired API key
`403`	Insufficient scope, live access not approved, or history limit
`404`	Not found (or feature disabled)
`422`	Validation failed
`429`	Rate limit or quota exceeded

All errors use the standard envelope. See error codes for every code value.

← All endpoints openapi.json