Skip to content

Documentation

API and webhooks

Fixes for REST API calls refused with 401, 403 or 429, webhook signatures that don't verify, failing or repeated webhook deliveries, and the audit stream to your security information and event management (SIEM) tool.

Where
Admin → Settings → Integrations → API Keys · Admin → Settings → Integrations → Webhooks · Admin → Settings → Organization settings → SIEM export · Admin → Audit logs → Security events
Permission
MANAGE_INTEGRATIONS (API keys, webhooks) · MANAGE_SETTINGS (SIEM export)
Updated
October 2026

Before you start

Each heading is an error or a symptom, with its cause and the fix.

REST API errors are JSON with an error message that names the problem, such as the missing scope.

Refused and throttled API calls are recorded in Admin → Audit logs → Security events as api_key.auth.failed, api_key.scope_denied or api_key.rate_limited.

Each endpoint on the Webhooks tab lists its five most recent deliveries, with the attempt count and the result.

The SIEM export tab shows the last error of each push subscription.

Problems and fixes

  1. 01

    401 “API key is required.”

    The call carried no key.

    • Send the key as Authorization: Bearer eventier_…
    • Or send the same value in an x-api-key header
    • Keys start with eventier_
    A call with the keybash
    curl -H "Authorization: Bearer eventier_…" \
      "https://<your-app-host>/api/v1/requests?limit=1"
  2. 02

    401 “API key is invalid.”

    The key is wrong, revoked or past its expiry date.

    • A key is shown once, when it is created; a copy that lost characters fails here
    • A key created with Expiry in days stops working on that date
    • Create a new key in Admin → Settings → Integrations → API Keys; creating one needs a sign-in in the last 10 minutes
    • 30 failed attempts in a minute from one address get 429 “Too many failed API authentication attempts.”
  3. 03

    401 “API key is disabled because the identity it belongs to is deactivated.”

    A personal key acts as the person who created it, and that person has been deactivated.

    • Create a replacement key under a service account: it keeps working when staff change
    • Or enable the person again in Admin → Users
  4. 04

    403 “API key is missing the required scope: …”

    The key wasn't given the scope this endpoint needs. Scopes are fixed when a key is created.

    • The message names the scope, such as requests:write
    • Create a new key with the scopes it needs, switch your integration to it, then revoke the old one
    • Creating a request needs requests:write; looking up a requestTypeId needs request-types:read
  5. 05

    403 “API key owner no longer has authority for scope” or “API key access was removed”

    A personal key can never do more than its owner can do now. When the owner loses a permission, the key loses the scopes that depend on it.

    • The owner must still hold MANAGE_INTEGRATIONS, or the key stops working
    • requests:read needs VIEW_ALL_REQUESTS; requests:write also needs EDIT_REQUESTS
    • request-types:read needs MANAGE_REQUEST_TYPES; users:read needs MANAGE_USERS
    • analytics:read needs VIEW_ALL_REQUESTS and VIEW_ANALYTICS
    • A service account's keys stop working if its role is changed from Agent
    • Restore the permission, or move the integration to a service account key
  6. 06

    429 “API rate limit exceeded”

    Each workspace gets 120 calls a minute across all its keys, and each key at most 90 of those.

    • “…for this key.”: this key used its share. “…for this organization.”: all keys together used the 120
    • Wait the number of seconds in Retry-After, then retry
    • Watch X-RateLimit-Remaining on every response and slow down before it reaches 0
    • Creating more keys doesn't raise the limit
    • Self-hosted: change the limits with API_RATE_LIMIT_PER_MINUTE and API_KEY_RATE_LIMIT_PER_MINUTE
    • The per-key limit defaults to three quarters of the workspace limit and never exceeds it
    1. HTTP/1.1 429 Too Many Requests
    2. Retry-After: 12
    3. X-RateLimit-Limit: 90
    4. X-RateLimit-Remaining: 0
    5. X-RateLimit-Org-Limit: 120
  7. 07

    Your receiver rejects the webhook signature

    The signature covers the exact bytes EvenTier sent. Parsing the JSON and serializing it again before you check changes those bytes.

    • Verify against the raw request body, before any JSON parsing
    • Read t and v1 from the x-eventier-webhook-signature header
    • Compute HMAC SHA-256 of <t>.<raw body> with the endpoint's signing secret, and compare the hex result to v1
    • Use the whole secret, whsec_ prefix included
    • Each endpoint has its own secret; a replaced endpoint's secret won't match
    • Allow up to 300 seconds between t and your clock, and keep the receiver's clock in sync
    • Each attempt is signed when it is sent, so a retry carries a new t
    Check one captured delivery by handbash
    # body.json: the raw body exactly as received
    # T: the t= value from x-eventier-webhook-signature
    # WHSEC: the endpoint's signing secret
    { printf '%s.' "$T"; cat body.json; } | openssl dgst -sha256 -hmac "$WHSEC"
    # The digest must equal the v1= value
  8. 08

    Webhook deliveries fail or keep retrying

    A delivery is tried three times a few seconds apart. While your endpoint keeps failing, it is retried in the background for about 24 hours.

    • Answer with a 2xx within 10 seconds; a slower answer counts as a failure
    • Redirects count as failures, so give the final URL
    • A 4xx other than 408, 425 or 429 is final and not retried
    • 5xx answers, 408, 425, 429 and timeouts are retried
    • Check the endpoint's Recent deliveries on the Webhooks tab: the attempt count and the HTTP status of the last attempt
    • Self-hosted: an event that still fails after about a day is set aside as failed, and the outbox health check counts it
  9. 09

    The same webhook event arrives more than once

    Delivery is at least once. A retry after a timeout can repeat an event your receiver already handled.

    • Record x-eventier-event-id and skip ids you have already processed; it stays the same on every retry
    • Return a 2xx right away and do slow work afterwards
  10. 10

    A delivery shows 0 attempts, or the webhook URL can't be saved

    EvenTier sends webhooks only to public HTTPS addresses. A URL that points into a private network is refused when you save it, or blocked before sending.

    • The URL must start with https://
    • Refused hosts: localhost and names ending in .local or .internal
    • Refused addresses: private and reserved IP ranges, including host names that resolve to one
    • A blocked delivery is recorded with 0 attempts and no HTTP status, and is not retried
    • Self-hosted: 0 attempts can also mean the signing secret can't be decrypted because SECRET_ENCRYPTION_KEY changed. Restore the key, or create the endpoint again
  11. 11

    The SIEM pull stream answers 401 “Invalid SIEM bearer token”

    The token is missing, wrong, revoked or past its expiry date.

    • Send it as Authorization: Bearer <token>
    • The SIEM export tab lists each token's expiry and status; an expired token reads Expired
    • A token is shown once, when generated; copy it into your SIEM straight away
    • Generate a new one on the SIEM export tab and revoke the old one
  12. 12

    The SIEM pull stream answers 410 CURSOR_EXPIRED

    The cursor can't be read, or it is an older id-style cursor whose event has since been deleted by retention.

    • Start again with ?since=<ISO 8601 time>, using the time of the last event you stored
    • Then pass each response's X-EvenTier-Next-Cursor back as ?cursor=
    Restart, then resumebash
    curl -H "Authorization: Bearer <token>" \
      "https://<your host>/api/audit/stream?since=2026-10-01T00:00:00Z"
    
    curl -H "Authorization: Bearer <token>" \
      "https://<your host>/api/audit/stream?cursor=<X-EvenTier-Next-Cursor>"
  13. 13

    The SIEM stream returns nothing new, or starts from the beginning

    An empty answer means no events since your cursor. Keep polling with the cursor you have.

    • Polling with a cursor, an empty page returns the same cursor in X-EvenTier-Next-Cursor; keep using it
    • Polling with since and no events yet, the header is empty; keep the same since
    • since must be an ISO 8601 time such as 2026-10-01T00:00:00Z. A value that can't be read is ignored, and the stream starts from the oldest event kept
    • limit sets the page size: 200 by default, 1,000 at most. X-EvenTier-Count says how many came back
    • More than 300 polls a minute from one address get 429 with Retry-After
    • Events older than the audit log's retention window are no longer available
  14. 14

    SIEM push deliveries fail

    Pushed events go to your HTTPS URL as signed POSTs, one per event. The SIEM export tab shows the last error for each subscription.

    • The signature header is X-EvenTier-Signature, in the same t=<unix time>,v1=<HMAC-SHA256> form as webhooks
    • The body is {"event": {...}}, signed exactly as sent
    • As with webhooks: public HTTPS addresses only, no redirects, and an answer within 10 seconds
    • Failed events are retried in the background, and the subscription stays enabled while it fails

Error messages

REST API and SIEM stream errors, with the HTTP status.

HTTPMessageWhat to do
401API key is required.Send Authorization: Bearer eventier_…
401API key is invalid.Check the key; create a new one if it was revoked or expired
401API key is disabled because the identity it belongs to is deactivated.Use a service account key
403API key is missing the required scope: <scope>.Create a key with that scope
403API key owner no longer has authority for scope: <scope>.Restore the owner's permission, or use a service account key
403API key access was removed when its owner's authority changed.Restore the owner's permission, or use a service account key
429API rate limit exceeded for this key.Wait for Retry-After; spread calls out
429API rate limit exceeded for this organization.Wait for Retry-After; all keys share the limit
429Too many failed API authentication attempts.Fix the key, then wait a minute
401Invalid SIEM bearer tokenUse a current SIEM token
410Cursor is invalid or has expired.Restart the stream with since=

Good to know

  • Give each integration its own key under a service account, with only the scopes it needs. Revoking one never breaks the others.
  • Keep the raw body and headers of one real delivery to test your signature check offline.
  • Check Admin → Audit logs → Security events for api_key.scope_denied and api_key.rate_limited before changing your code.