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
- 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-keyheader - Keys start with
eventier_
A call with the keybash curl -H "Authorization: Bearer eventier_…" \ "https://<your-app-host>/api/v1/requests?limit=1" - Send the key as
- 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.”
- 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
- 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 arequestTypeIdneedsrequest-types:read
- The message names the scope, such as
- 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:readneedsVIEW_ALL_REQUESTS;requests:writealso needsEDIT_REQUESTSrequest-types:readneedsMANAGE_REQUEST_TYPES;users:readneedsMANAGE_USERSanalytics:readneedsVIEW_ALL_REQUESTSandVIEW_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
- The owner must still hold
- 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-Remainingon 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_MINUTEandAPI_KEY_RATE_LIMIT_PER_MINUTE - The per-key limit defaults to three quarters of the workspace limit and never exceeds it
- HTTP/1.1 429 Too Many Requests
- Retry-After: 12
- X-RateLimit-Limit: 90
- X-RateLimit-Remaining: 0
- X-RateLimit-Org-Limit: 120
- 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
tandv1from thex-eventier-webhook-signatureheader - Compute HMAC SHA-256 of
<t>.<raw body>with the endpoint's signing secret, and compare the hex result tov1 - 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
tand 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 - 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
outboxhealth check counts it
- 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-idand skip ids you have already processed; it stays the same on every retry - Return a 2xx right away and do slow work afterwards
- Record
- 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
.localor.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_KEYchanged. Restore the key, or create the endpoint again
- 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
- Send it as
- 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-Cursorback 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>" - Start again with
- 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
sinceand no events yet, the header is empty; keep the samesince sincemust be an ISO 8601 time such as2026-10-01T00:00:00Z. A value that can't be read is ignored, and the stream starts from the oldest event keptlimitsets the page size: 200 by default, 1,000 at most.X-EvenTier-Countsays 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
- Polling with a cursor, an empty page returns the same cursor in
- 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 samet=<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
- The signature header is
Error messages
REST API and SIEM stream errors, with the HTTP status.
| HTTP | Message | What to do |
|---|---|---|
| 401 | API key is required. | Send Authorization: Bearer eventier_… |
| 401 | API key is invalid. | Check the key; create a new one if it was revoked or expired |
| 401 | API key is disabled because the identity it belongs to is deactivated. | Use a service account key |
| 403 | API key is missing the required scope: <scope>. | Create a key with that scope |
| 403 | API key owner no longer has authority for scope: <scope>. | Restore the owner's permission, or use a service account key |
| 403 | API key access was removed when its owner's authority changed. | Restore the owner's permission, or use a service account key |
| 429 | API rate limit exceeded for this key. | Wait for Retry-After; spread calls out |
| 429 | API rate limit exceeded for this organization. | Wait for Retry-After; all keys share the limit |
| 429 | Too many failed API authentication attempts. | Fix the key, then wait a minute |
| 401 | Invalid SIEM bearer token | Use a current SIEM token |
| 410 | Cursor 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_deniedandapi_key.rate_limitedbefore changing your code.