Project Event Ingestion Guide
Language: English. Selecting a supported site language opens that language's guide. Technical API names and examples remain in their protocol-defined form; the event-catalog API localizes its own returned labels independently.
This guide explains how an application sends events to Givemora using a project credential. It covers project setup, the event API, batch requests, signed requests, the standard event catalog, payload rules, responses, retries, and troubleshooting.
Base URL: https://givemora.com
Contents
- Set up a project credential
- Send one event
- Send a batch
- Event body reference
- Standard event catalog and profile schemas
- Event intake options
- Routing results
- Idempotency and safe retries
- Limits and errors
- Security and data handling
- Quick checklist
- Workspaces, projects, roles, and credentials
- Read events, receipts, delivery diagnostics, and usage
- Use Telegram to manage personal event notifications
- Run reports, create exports, and schedule delivery
- Choose an SDK or call the HTTP API directly
- Advanced APIs and authorization boundaries
- Agent handoff and troubleshooting
1. Set up a project credential
Create or select a project in the Givemora workspace you manage. A workspace is the access and billing boundary; a project groups an application's event stream and destinations. Issue a separate project credential for each project and environment. Supported environments are development, staging, and production; the credential determines the event environment, so do not send an environment property in the event body.
You can issue a credential in the owner dashboard or with the management API. Management tokens and project credentials are different:
- A management token, usually prefixed
gm_owner_, manages workspace and project resources. It is not an event-ingestion key. - A project credential, prefixed
gm_project_, has theevents:writescope and sends events for one project and one environment.
To issue a project credential through the management API, use a management token with credentials:manage scope and the project ID:
export GIVEMORA_MANAGEMENT_TOKEN='gm_owner_...'
export GIVEMORA_PROJECT_ID='your-project-id'
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/projects/${GIVEMORA_PROJECT_ID}/credentials" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: issue-production-ingest-key-001' \
--data '{"name":"Production event sender","environment":"production"}'
The response contains the project credential in data.token. Save it in a server-side secret manager immediately: the token is shown only in that successful issuance response. Replaying the same idempotency key does not reveal it again. Do not put it in browser JavaScript, a mobile app, source control, event payloads, or logs. If it is lost or exposed, issue a replacement, update the sender, verify the new key, then revoke the old credential.
First key without a prior key
A project key is not needed to request the first one. The workspace and project must already exist. Submit the request below from a trusted server process. It generates a retrieval proof and saves that proof, the exact request body, and the idempotency key in a private local state file before the first network call. Keep that state file: retries must reuse the same values. For production, replace the example key file with your organization’s secret manager. The sample uses file mode 0600 and never prints the key.
Once approved and claimed, the credential is a normal events:write project key with no expiry by default. The sample generates 32 random bytes, producing a 43-character base64url proof. The API accepts proof values from 43 through 128 base64url characters; generate at least 32 random bytes.
The example uses a separate directory for workspace, project, and environment: ~/.config/givemora/projects/fusionpointai/fusionpointai/production. Use matching unique components for each real target so files do not collide.
import json
import os
import secrets
import tempfile
import time
import urllib.request
from pathlib import Path
BASE = "https://givemora.com/v1"
# Keep each workspace/project/environment in its own directory.
PROJECT_DIR = Path.home() / ".config/givemora/projects/fusionpointai/fusionpointai/production"
STATE = PROJECT_DIR / "request.json"
KEY_FILE = PROJECT_DIR / "project.key"
def save_private(path, value):
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
os.chmod(path.parent, 0o700)
fd, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
temporary_path = Path(temporary_name)
try:
os.fchmod(fd, 0o600)
stream = os.fdopen(fd, "w")
fd = None
with stream:
stream.write(value)
stream.flush()
os.fsync(stream.fileno())
os.replace(temporary_path, path)
directory_fd = os.open(path.parent, os.O_RDONLY)
try:
os.fsync(directory_fd)
finally:
os.close(directory_fd)
finally:
if fd is not None:
os.close(fd)
try:
temporary_path.unlink()
except FileNotFoundError:
pass
def read_private(path):
os.chmod(path, 0o600)
return path.read_text()
def call(method, path, body=None, bearer=None, headers=None):
data = None if body is None else json.dumps(body).encode()
request_headers = {"Accept": "application/json"}
if data is not None:
request_headers["Content-Type"] = "application/json"
if bearer:
request_headers["Authorization"] = f"Bearer {bearer}"
request_headers.update(headers or {})
request = urllib.request.Request(BASE + path, data=data, headers=request_headers, method=method)
with urllib.request.urlopen(request, timeout=20) as response:
return response.status, json.load(response)
# Save the proof, exact request body, and idempotency key before the first POST.
if STATE.exists():
state = json.loads(read_private(STATE))
else:
proof = secrets.token_urlsafe(32) # 43 base64url characters
state = {
"proof": proof,
"idempotency_key": secrets.token_urlsafe(24),
"body": {
"workspace_name": "fusionpointai",
"project_slug": "fusionpointai",
"environment": "production",
"name": "fusionpointai production",
"retrieval_proof": proof,
},
}
save_private(STATE, json.dumps(state))
status_code, result = call(
"POST", "/project-credential-requests", state["body"],
headers={"Idempotency-Key": state["idempotency_key"]},
)
request_id = result["data"]["id"]
print("Request code:", result["data"]["request_code"])
# Poll with the retrieval proof. Approval is a separate God decision.
while True:
_, result = call("GET", f"/project-credential-requests/{request_id}", bearer=state["proof"])
request_status = result["data"]["status"]
if request_status in {"approved", "issued"}:
break
if request_status == "acknowledged":
if KEY_FILE.exists():
print("The acknowledged project key is already stored at:", KEY_FILE)
raise SystemExit(0)
raise RuntimeError("The acknowledged key is not available locally; request a replacement.")
if request_status in {"rejected", "expired"}:
raise RuntimeError(f"Request ended with status: {request_status}")
time.sleep(result["data"].get("poll_interval", 5))
# An issued request replays the encrypted delivery for 15 minutes; a saved key can be acknowledged later.
if request_status == "issued" and KEY_FILE.exists():
project_key = read_private(KEY_FILE)
else:
_, result = call("POST", f"/project-credential-requests/{request_id}/claim", bearer=state["proof"])
project_key = result["data"]["token"]
save_private(KEY_FILE, project_key)
# Acknowledge only after the key has been stored; this clears encrypted delivery material.
call(
"POST", f"/project-credential-requests/{request_id}/acknowledge",
{"token": project_key}, bearer=state["proof"],
)
print("Project key stored with owner-only file permissions at:", KEY_FILE)
The response is an opaque 202 Accepted request, not an active key. It includes a human-readable request code and a five-second suggested polling interval. The 202 response contains data.id, data.request_code, data.status, data.expires_at, data.poll_interval (5 seconds), and data.revision. It does not contain a project key; a key exists only after God approves the request and the client claims it. The submitted name is not verified; give the request code to a System God through a trusted channel so the target can be checked. If the names do not uniquely resolve to an existing workspace/project pair, submit a new request with workspace_id and project_id. Unknown or ambiguous targets still receive the same opaque 202 response. Approval is required before claim. The sample waits for approval, claims the key, stores it, then acknowledges possession. Acknowledgement clears the encrypted delivery copy immediately; if the client has not acknowledged, it is cleared after 15 minutes. The request proof and idempotency key must not be logged or shared.
When a new request clearly matches one existing workspace and project and is ready for review, active System God staff receive a private Telegram notification in their own interface language. The message includes the request and project details, with Approve and Reject buttons; either choice still requires the existing Secure App confirmation. Retrying the same API request does not send duplicate alerts. Before applying a decision, the system checks the request’s current state and expiry, and the staff member’s current role and linked identity again. The requester name is unverified, so check the request code with a trusted project contact. Developers can wait for approval; no one needs to arrange the initial key issuance manually.
Pending and approved-but-unclaimed requests expire after 24 hours. Limits: creation is 5 per minute per IP; proof operations are 30 per minute per request and IP plus an aggregate 120 per minute per IP. Claim bodies are capped at 8 KiB; the global pending cap is 10,000. Every 429 includes Retry-After. The Idempotency-Key header must contain 1–128 printable ASCII characters. Request and idempotency metadata remains available for 30 days after request expiry, then is purged. The 15-minute replay expiry clears only encrypted delivery material; it never revokes the non-expiring key, which has no expiry by default. If the client has the key, it may acknowledge later by proving possession. If it lost the key after the replay window, it needs a new request or authorized issuance.
Pending capacity is 100 per resolved workspace/project pair, 10 per unresolved reference pair, and 1,000 unresolved globally within 10,000 total. Idempotent retries do not use another slot. Capacity exhaustion returns 429 with Retry-After.
export GIVEMORA_PROJECT_KEY="$(cat "$HOME/.config/givemora/projects/fusionpointai/fusionpointai/production/project.key")"
curl --fail-with-body --request POST 'https://givemora.com/v1/events' \
--header "Authorization: Bearer ${GIVEMORA_PROJECT_KEY}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: fusionpointai-deployment-001' \
--data '{
"id":"fusionpointai-deployment-001",
"type":"deployment.completed",
"occurred_at":"2026-11-02T12:00:00Z",
"severity":"success",
"data":{"summary":"fusionpointai production deployment completed"}
}'
unset GIVEMORA_PROJECT_KEY
2. Send one event
Send JSON to POST /v1/events. Authenticate with the project credential as a bearer token:
export GIVEMORA_PROJECT_KEY='gm_project_...'
curl --fail-with-body --request POST 'https://givemora.com/v1/events' \
--header "Authorization: Bearer ${GIVEMORA_PROJECT_KEY}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: user-usr_123-signed-up-v1' \
--data '{
"id": "user-usr_123-signed-up-v1",
"type": "user.signed_up",
"occurred_at": "2026-09-24T18:30:00Z",
"severity": "info",
"data": {
"summary": "A new user created an account",
"user_id": "usr_123",
"registration_method": "email"
},
"actor": {"type": "user", "id": "usr_123"},
"tags": ["identity", "signup"],
"correlation_id": "request-abc-123"
}'
The body above is an example. Use identifiers and values from your application. The credential supplies the project and environment; the body supplies the event type, time, severity, and event data.
Accepted response
A valid event returns HTTP 202 Accepted, for example:
{
"accepted": true,
"event_id": "01...",
"duplicate": false,
"received_at": "2026-09-24T18:30:01+00:00",
"routing": "queued",
"routing_reason": null,
"routing_explain": null,
"schema_id": null,
"schema_version": null,
"schema_warnings": [],
"request_id": "01..."
}
accepted: true means Givemora accepted and stored the event. It does not guarantee that a notification was delivered. Delivery is asynchronous. routing and routing_reason explain what happened to notification routing; see Routing results.
3. Send a batch
For multiple events, send a JSON array to POST /v1/events/batch. Every element is an event object with the same fields as a single event. Include a unique, stable id in every event so each item can be retried safely.
curl --fail-with-body --request POST 'https://givemora.com/v1/events/batch' \
--header "Authorization: Bearer ${GIVEMORA_PROJECT_KEY}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '[
{
"id":"invoice-inv_800-issued-v1",
"type":"billing.invoice_issued",
"severity":"success",
"data":{
"workspace_id":"ws_42",
"invoice_id":"inv_800",
"invoice_number":"800",
"amount_minor":1299,
"currency":"USD",
"summary":"Invoice 800 was issued"
}
},
{
"id":"invoice-inv_799-paid-v1",
"type":"billing.invoice_paid",
"severity":"success",
"data":{
"workspace_id":"ws_42",
"invoice_id":"inv_799",
"amount_minor":1299,
"currency":"USD"
}
}
]'
The batch response is HTTP 202 and contains an items array. Each result includes its original index; a valid item may be accepted even if another item fails validation or quota checks. Inspect each item rather than treating the batch-level accepted flag as proof that every event succeeded. For batches, set a stable id on every item; each event's id deduplicates that event. Separately, POST /v1/events/batch accepts an optional Idempotency-Key for batch-receipt replay, scoped to the workspace, project, and environment. Repeating the key with the same JSON value (object key order is canonicalized; array order is significant) replays the compact receipt; reusing it with different content returns HTTP 409 idempotency_conflict. Keep each event ID stable when retrying a batch, especially after a timeout that may follow partial processing.
If ingestion capacity is temporarily unavailable after batch processing has begun, the API can return HTTP 503 with a receipt_id and status: incomplete, without an items array. If you sent an Idempotency-Key, retry the exact ordered body with the same key to resume and read that receipt; do not infer which items were accepted from the incomplete response. Without an idempotency key, a retry creates a new receipt, although stable event IDs still deduplicate accepted items. A top-level malformed body, oversized request, or too many items rejects the entire request before per-item processing.
4. Event body reference
Structured CloudEvents and opaque binary data
The API also accepts CloudEvents 1.0 structured JSON at POST /v1/events with Content-Type: application/cloudevents+json. Bounded structured batches use POST /v1/events/batch with Content-Type: application/cloudevents-batch+json. Each CloudEvent must contain exactly one of data or data_base64.
Use data_base64 when the event data is an opaque byte sequence. Givemora validates strict canonical RFC 4648 base64 and stores the original canonical base64 string in a reserved wrapper under the ordinary event data object:
{
"specversion": "1.0",
"id": "document-42-uploaded",
"source": "urn:example:documents",
"type": "document.uploaded",
"datacontenttype": "application/pdf",
"data_base64": "JVBERi0xLjQK..."
}
The stored canonical event data has this shape:
{
"data": {
"_givemora_binary": {
"encoding": "base64",
"value": "JVBERi0xLjQK..."
}
}
}
The bytes are opaque. Even if decoding them produces valid JSON, Givemora does not parse or reinterpret them. The original datacontenttype remains in context.cloud_event; base64 events may use non-JSON media types such as application/pdf. The decoded byte count is capped by personal.limits.event_payload_bytes (256 KiB by default). A single-event request body is also subject to that event-size limit. Structured batch requests retain their separate overall request-size and item-count limits, and each normalized event still passes the per-event size validation. The stored canonical JSON includes the wrapper and CloudEvents context metadata, so its serialized byte count can be larger than the decoded data; the adapter stores the base64 value once and never expands decoded bytes into the event payload. Sending both data and data_base64, malformed or non-canonical base64, or a non-string value is rejected with a safe validation detail.
CloudEvents HTTP binary content mode
For senders that already have raw bytes, POST /v1/events also accepts CloudEvents HTTP binary mode. Send the bytes unchanged as the request body. Set Content-Type to the byte content's media type; Givemora preserves that exact value as CloudEvents datacontenttype. Do not send ce-datacontenttype.
Send the required ce-specversion: 1.0, ce-id, ce-source, and ce-type headers. Supported optional scalar headers are ce-time, ce-subject, ce-dataschema, ce-correlationid, ce-severity, ce-traceparent, and ce-tracestate. Header values are unescaped as HTTP quoted strings when quoted, then percent-decoded exactly once. Malformed, duplicate, invalid UTF-8, or control-character values are rejected. ce-actor and ce-tags are structured JSON extensions and are available through structured CloudEvents JSON only. A normal W3C traceparent request header takes precedence over ce-traceparent for the HTTP trace.
The raw body is opaque, including empty bytes, NULs, invalid UTF-8, or bytes that happen to form JSON. The raw-byte limit is personal.limits.event_payload_bytes (256 KiB by default); a body at the limit is accepted and a larger body is rejected with HTTP 413. /v1/events/batch remains structured-only. Binary content and structured data_base64 use the same canonical stored representation and deduplicate when their source and event ID match.
Binary request signatures are optional, like existing ingestion signatures. If any X-Givemora-Timestamp, X-Givemora-Nonce, or X-Givemora-Signature header is supplied, all three are required. Sign the exact raw body and normalized CloudEvents attribute map using the bearer credential as the HMAC key. Add the exact Content-Type value as datacontenttype when present, sort attribute keys lexicographically, serialize canonical JSON with unescaped Unicode and slashes, and calculate:
signing_input = "givemora-cloudevents-http-binary-v1\n" + timestamp + "\n" + nonce + "\n" + canonical_json + "\n" + lowercase_hex(SHA256(raw_body))
signature = "sha256=" + lowercase_hex(HMAC-SHA256(bearer_credential, signing_input))
The canonical JSON contains the normalized lowercase CloudEvents attribute names and their decoded values. Existing timestamp tolerance and nonce-replay checks apply. Legacy body-only signatures are not valid for binary mode. Never log or include the raw bytes or signature input in notifications, reports, telemetry, or audit output.
Binary wrappers are excluded from saved-report allowlists, previews, and exports. Do not place credentials or other secrets in binary event data. Project users authorized to read the event may read its stored event payload.
| Field | Requirement and rules |
|---|---|
id |
Optional string, 1–128 characters. Strongly recommended: create a stable unique ID for every logical event and reuse it for retries. |
type |
Required string, 1–100 characters. Must be lowercase canonical segments separated by dots, such as user.signed_up or orders.payment_failed. |
occurred_at |
Optional RFC 3339 timestamp that includes a timezone, such as 2026-09-24T18:30:00Z or 2026-09-24T22:00:00+03:30. |
severity |
Optional info, success, warning, or critical. If omitted, ingestion uses info; it does not automatically apply the catalog's recommended severity. |
data |
Optional JSON object for event-specific fields. data.summary may contain a human-readable summary of up to 500 characters. |
data.summary_translations |
Optional object with up to eight supported-language keys (en, fa, ar, es, fr, de, pt-BR, zh-CN) and a summary string of up to 500 characters for each. Notifications use the matching translation when present; otherwise they use data.summary as supplied. |
context |
Optional JSON object for application, request, deployment, or source context. |
actor |
Optional JSON object describing who or what initiated the action. |
subject |
Optional JSON object describing the entity affected by the action. |
tags |
Optional array of up to 20 distinct strings; each string must be 1–50 characters. |
correlation_id |
Optional string, 1–128 characters, useful for connecting related events across a workflow. |
data, context, actor, and subject must be JSON objects, not arrays. The complete body may be nested no deeper than 10 levels. Unknown top-level fields are rejected; put custom properties inside data, context, actor, or subject. The common ingestion validator recursively redacts values under the exact property names password, secret, token, access_token, refresh_token, api_key, authorization, and cookie (case-insensitive). This limited redaction is defense in depth; applications must not send secrets in the first place.
The event catalog's required_fields and optional_fields are the recommended contract for each standard event. Ingestion validates the common event envelope, but does not enforce those event-specific fields. Send the recommended required fields so that the event remains useful to your team and notification recipients.
5. Standard event catalog
The public catalog endpoint is GET /v1/event-catalog. It requires no credential and is limited to 60 requests per minute. It returns the versioned catalog, descriptions, categories, recommended severity, suggested fields, and privacy guidance. These names are recommended, not an allowlist: a project may send any type that follows the canonical syntax, unless that project's routing policy filters it.
| Event type | Meaning | Recommended severity | Recommended required data | Recommended optional data |
|---|---|---|---|---|
user.signed_up |
A user account was created. | info |
user_id |
registration_method, email_domain |
user.logged_in |
A user authenticated successfully. | info |
user_id |
method, ip_country |
user.logged_out |
A user signed out. | info |
user_id |
method |
user.email_verified |
A user verified their email address. | success |
user_id |
verification_method |
authenticator.code_sent |
A one-time or authenticator code was sent. Never send the code itself. | info |
user_id, channel |
attempt_id, expires_at |
authenticator.code_verified |
A one-time or authenticator code was verified. | success |
user_id |
attempt_id, channel |
authenticator.code_failed |
Code verification failed. | warning |
user_id |
attempt_id, channel, reason |
authenticator.mfa_enabled |
Multi-factor authentication was enabled. | success |
user_id |
method |
authenticator.mfa_disabled |
Multi-factor authentication was disabled. | warning |
user_id |
method, reason |
security.suspicious_login |
A suspicious sign-in was detected. | warning |
user_id |
reason, ip_country, method |
security.account_locked |
An account was locked. | warning |
user_id |
reason, lock_until, attempt_count |
security.password_reset_abuse |
Suspicious password-reset activity was detected. | warning |
user_id |
reason, ip_country, attempt_count |
security.api_key_created |
An API key was created. Never include its value. | info |
actor_user_id |
key_id, scope, workspace_id, project_id |
security.api_key_revoked |
An API key was revoked. Never include its value. | warning |
actor_user_id |
key_id, reason, workspace_id, project_id |
user.deleted |
A user account was deleted. | info |
user_id |
deletion_method, reason |
user.password_changed |
A user's password was changed. Never include a password or hash. | success |
user_id |
method |
user.password_reset_requested |
A password reset was requested. Never include reset tokens or codes. | info |
user_id |
channel, request_id, expires_at |
user.password_reset_completed |
A password reset was completed. Never include reset tokens or codes. | success |
user_id |
method, request_id |
user.invited |
A user was invited to an application or workspace. | info |
invited_user_id, inviter_user_id |
invitation_id, workspace_id, expires_at |
user.invitation_accepted |
A user accepted an invitation. | success |
user_id |
invitation_id, workspace_id |
session.created |
An authenticated session was created. Never include session tokens or cookies. | info |
user_id |
session_id, method, ip_country |
session.revoked |
An authenticated session was revoked. Never include session tokens or cookies. | info |
user_id |
session_id, reason, actor_user_id |
access.role_granted |
A role was granted to a user or service account. | info |
subject_user_id, role |
actor_user_id, workspace_id, project_id |
access.role_revoked |
A role was revoked from a user or service account. | warning |
subject_user_id, role |
actor_user_id, workspace_id, project_id |
access.permission_denied |
An authorization check denied an action. | warning |
user_id, permission |
resource_type, resource_id, reason |
project.created |
A project was created. | info |
project_id |
workspace_id, slug |
project.archived |
A project was archived. | info |
project_id |
workspace_id, reason |
integration.connected |
An external integration was connected. Never include credentials. | success |
integration |
provider, integration_id, workspace_id, project_id |
integration.disconnected |
An external integration was disconnected. | warning |
integration |
provider, integration_id, workspace_id, project_id, reason |
billing.invoice_issued |
An invoice was issued. | success |
workspace_id, invoice_id, invoice_number, amount_minor, currency |
plan, due_at |
billing.invoice_paid |
An invoice was paid. | success |
workspace_id, invoice_id, amount_minor, currency |
invoice_number, payment_id |
billing.invoice_overdue |
An invoice passed its due date unpaid. | warning |
workspace_id, invoice_id, due_at |
invoice_number, amount_minor, currency |
billing.subscription_started |
A subscription became active. | success |
workspace_id, plan |
subscription_id, billing_interval |
billing.subscription_canceled |
A subscription was canceled. | warning |
workspace_id |
subscription_id, plan, reason, canceled_at |
billing.payment_succeeded |
A payment completed successfully. | success |
workspace_id |
payment_id, currency, amount_minor |
billing.payment_failed |
A payment attempt failed. | warning |
workspace_id |
payment_id, reason |
billing.payment_refunded |
A payment was refunded. | warning |
workspace_id |
payment_id, amount_minor, currency, reason |
system.job_succeeded |
A background job completed. | success |
job |
job_id, duration_ms |
system.job_failed |
A background job failed after application-level handling. | critical |
job |
job_id, reason, attempt |
system.webhook_failed |
An inbound or outbound webhook failed processing. | warning |
webhook_id |
provider, reason, attempt |
Discover profile schemas and privacy guidance
GET /v1/event-catalog is public and returns the catalog and profile schemas. Send Accept-Language to request a supported interface locale. No project credential or management token is needed:
curl --fail-with-body 'https://givemora.com/v1/event-catalog' \
--header 'Accept: application/json' \
--header 'Accept-Language: en'
The API response is the current source of truth for the deployed catalog and template set. Do not rely on a version or profile count copied into this guide: query the endpoint when you need the current values. The 40 recommended event types listed above and the 15 optional starter profiles below describe the source catalog; templates are advisory contracts, not an event-type allowlist. Two profiles can use the same event type while recommending different data shapes.
| Response field | Meaning |
|---|---|
data.version |
Event catalog version. |
data.events |
Localized event definitions, including event type, category, recommended severity and fields, and available privacy guidance. |
data.template_version |
Version of the JSON template set returned by this response. |
data.templates[] |
Typed profiles with synthetic examples, JSON Schema, privacy classification, allowed fields and exclusions. |
data.locale |
Locale selected for the response. |
data.usage |
Canonical ingestion endpoint and localized usage note. |
request_id and X-Request-Id |
Correlate the response with support or server diagnostics; neither contains a credential. |
Each item in data.templates provides its stable name, event_type, category, default_severity, privacy_classification, required_fields, optional_fields, forbidden_fields, synthetic example, and JSON Schema Draft 2020-12 schema. The schema describes a closed common envelope and the profile-specific data shape: it requires type, severity, and data, while the normal ingestion validator requires type, allows omitted data, and stores omitted severity as info. The endpoint does not enforce these template schemas or event-specific required fields. The custom profile permits a canonical dotted type but still limits its data to summary and metadata. Amounts are non-negative integers, currencies are three uppercase letters, attempts are positive integers, and date-time fields use the JSON Schema date-time format.
The response also includes privacy_profile.allowed_data_fields, privacy_profile.enforced_forbidden_field_policy scoped to recursive object property names, and privacy_profile.recommended_exclusions by data class. The template schema's forbidden-key policy blocks listed aliases case-insensitively, including nested objects and objects inside arrays. A name that merely contains a sensitive word is not rejected by substring. Its policy version is the enclosing template-set revision. privacy_profile.recommended_exclusions.value_content_scanned is false: neither the template policy nor the common ingestion validator scans arbitrary text or other values for secrets. The profile policy is stricter than the common intake redactor; use the schema for client-side template checks and keep all secret and sensitive values out of events regardless of key name.
translation_status is available when localized_name is an exact translation for the selected locale. If that translation is unavailable and the configured default-locale label exists, the status is fallback: localized_name contains the default-locale value, fallback_locale names that locale, and translation_fallback_label explains the fallback in the selected interface locale. If a usable default label or translated fallback label is unavailable, the status is missing; localized_name, fallback_locale, and translation_fallback_label are null. Consumers should branch on translation_status and display the supplied label for fallback; for missing, use the stable profile name or event_type. Do not invent translated prose. The API's returned schema and policy are authoritative for each response. The repository-only template source is resources/event-templates/v1/templates.json; public clients should use GET /v1/event-catalog rather than depend on repository files. The 15 current source profile names are signup, authentication_challenge_sent, authentication_challenge_succeeded, authentication_challenge_failed, invoice_issued, invoice_paid, invoice_overdue, payment_attempt_confirmed, payment_attempt_failed, subscription_started, subscription_renewal_payment, subscription_canceled, job_failure_incident, webhook_failure_incident, and generic_custom_event.
The event-level required_fields in the catalog and template schemas are recommendations for constructing useful events. The current ingestion API validates its common envelope but does not enforce every template's event-specific required fields. Telegram catalog discovery and command synchronization are separate surfaces; this API documentation does not establish their live registration or menu parity.
6. Event intake options
| Request | Use it when | Authentication |
|---|---|---|
POST /v1/events |
Your application can construct Givemora's event JSON. Recommended for direct integrations. | Project bearer credential. Givemora HMAC headers are optional. |
POST /v1/events/batch |
Your application has several events ready to send together. | Project bearer credential. Givemora HMAC headers are optional. |
POST /v1/hooks/{source} |
A provider posts its native webhook body and you want Givemora to wrap it as an event. | Project bearer credential plus a valid signature. |
For direct provider delivery, the request needs both Authorization: Bearer <project-credential> and a valid signature. For supported providers, if a recognized native signature header is present, Givemora verifies it with the same project credential as the secret. This means the provider must be configurable to send that exact project credential as its signing secret as well as attach it as a bearer header. If the provider cannot do both, verify its signature in your application or gateway, then forward a normalized event to POST /v1/events with the bearer credential. A listed adapter alone does not make a provider direct integration compatible.
For a generic signed request, send all three headers: X-Givemora-Timestamp (Unix seconds), X-Givemora-Nonce (a unique printable value), and X-Givemora-Signature. Compute the signature over the exact request body bytes:
sha256=hex(HMAC-SHA256(project_credential, timestamp + "." + nonce + "." + raw_body))
The timestamp must be within five minutes of server time by default. A nonce cannot be reused with the same credential. If any Givemora signature header is sent, all three must be valid. Generic webhook ingestion at /v1/hooks/{source} always requires a signature. The ordinary /v1/events and batch endpoints accept bearer authentication without a request signature, unless signature headers are supplied.
For /v1/hooks/{source}, the source is a lowercase identifier of up to 32 characters. Givemora wraps the received JSON body under data and derives an event type from provider headers or the source name. Optional headers can set X-Givemora-Event-Type, X-Givemora-Event-Id, X-Givemora-Occurred-At, and X-Givemora-Severity. Native signature adapters exist for Stripe, GitHub/GitHub App, GitLab, Slack, and Shopify. The verifier uses the project credential as the signature secret; only use a native provider route when that provider can be configured to sign with this same secret. Otherwise, verify the provider signature in your application and forward a normalized event to POST /v1/events.
This Node.js example sends a custom provider-shaped JSON body through the generic signed webhook route. The body is signed exactly as sent; the X-Givemora-Event-* headers provide the canonical event envelope:
import { createHmac, randomUUID } from 'node:crypto';
const credential = process.env.GIVEMORA_PROJECT_KEY;
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomUUID();
const body = JSON.stringify({
user_id: 'usr_123',
summary: 'A new user created an account',
registration_method: 'email',
});
const signature = createHmac('sha256', credential)
.update(`${timestamp}.${nonce}.${body}`)
.digest('hex');
const response = await fetch('https://givemora.com/v1/hooks/my_app', {
method: 'POST',
headers: {
Authorization: `Bearer ${credential}`,
Accept: 'application/json',
'Content-Type': 'application/json',
'X-Givemora-Timestamp': timestamp,
'X-Givemora-Nonce': nonce,
'X-Givemora-Signature': `sha256=${signature}`,
'X-Givemora-Event-Type': 'user.signed_up',
'X-Givemora-Event-Id': 'user-usr_123-signed-up-v1',
'X-Givemora-Severity': 'info',
},
body,
});
console.log(response.status, await response.json());
7. Routing results
Accepted events are stored even when notification routing is paused, muted, or filtered. A successful HTTP response means ingestion succeeded; check the response's routing fields to understand notification handling.
routing |
Meaning |
|---|---|
queued |
The event was accepted for asynchronous notification processing. This does not guarantee an eligible destination is configured or that a provider will deliver the notification. If no eligible destination is available, the delivery attempt is recorded as destination_missing. |
paused |
The project has notifications paused. The event is still stored. |
muted |
A project event policy is currently muted. The event is still stored. |
filtered |
An event-type allowlist, severity threshold, rule, cooldown, or plan restriction suppressed routing. The event is still stored. |
quarantined |
A registered project schema policy accepted the event into quarantine after schema validation failed. Inspect the returned routing_explain metadata and the schema quarantine view; this is separate from the advisory standard profiles in the public catalog. |
heartbeat |
The event was recorded as a heartbeat signal; it is not a regular notification. |
synthetic |
The event is a synthetic check that is not being sent as a normal notification. |
Common routing_reason values include project_paused, muted_until, event_type_not_allowed, severity_below_threshold, rule_not_matched, cooldown_active, paid_channel_restricted, heartbeat_observed, synthetic_check, and schema_validation_failed. A null reason generally means no suppression reason was recorded. The exact explanation, when available, is returned in routing_explain.
To inspect stored events, use a management token with events:read on GET /v1/manage/projects/{project_id}/events. That read endpoint is separate from the project credential; ingestion keys only write events.
The endpoint returns newest events first and uses cursor pagination. limit defaults to 10 and can be set up to 50. Pass the opaque next_cursor from one response as cursor on the next request; continue until next_cursor is null. You may keep the optional environment filter on every page.
8. Idempotency and safe retries
For a single event, send a stable unique id in the body. You may also send an Idempotency-Key header; if both are present, they must match. When the same project, environment, key, and body are sent again, Givemora returns 202 with duplicate: true without storing a second copy. Reusing a key with a different body returns 409 idempotency_conflict.
For batches, set a stable id on every item; each event's id deduplicates that event. Separately, POST /v1/events/batch accepts an optional Idempotency-Key for batch-receipt replay, scoped to the workspace, project, and environment. Repeating the key with the same JSON value replays the compact receipt. Object key order is canonicalized, but array order is significant. A changed request with the same key returns HTTP 409 idempotency_conflict. Keep each event ID stable when retrying a batch, especially after a timeout that may follow partial processing. If the server returns an incomplete batch receipt, retry the exact body and key to resume it; do not change array order or infer item outcomes from a response with no items.
The deduplication horizon for producer event keys and keyed batch receipts is configured by PERSONAL_IDEMPOTENCY_RETENTION_DAYS (personal.ingestion.idempotency_retention_days), which defaults to 30 days. While the key or receipt is unexpired, matching retries reuse the stored outcome. After that window expires, the same producer key may be accepted as a new event and produce new side effects. Event-payload retention is configured separately.
Retry network failures and temporary 5xx errors, plus 429 rate-limit responses, with exponential backoff and jitter. Honor Retry-After when present. Do not repeatedly retry 400, 401, 403, or 422 errors without correcting the request. A 409 idempotency_conflict means the key was already used for a different event body; generate a new event ID only if it is a genuinely different logical event.
9. Limits and errors
The following are the application's default limits; deployments may override the byte and rate settings:
| Limit | Default |
|---|---|
| Single event JSON body | 256 KiB |
| Batch JSON body | 5 MiB |
| Events per batch | 100 |
| Maximum event nesting depth | 10 |
data.summary length |
500 characters |
| Translated summaries | 8 entries, each up to 500 characters |
| Tags | 20; each 1–50 characters |
| Event type | 1–100 characters |
| Pre-authentication source-IP requests | 600 per minute |
| Per credential ingestion requests | 60 per minute |
| Per project ingestion requests | 120 per minute |
| Per workspace ingestion requests | 300 per minute |
The rate limits count HTTP requests; one batch request counts as one request, while each accepted event still counts toward billing and event usage quotas. Limits are defaults and deployments can configure tighter or different values. GET /v1/manage/usage/events reports consumed usage totals; it does not return the effective plan quota.
| HTTP status | Typical error codes | What to do |
|---|---|---|
400 |
malformed_json |
Send valid JSON. |
401 |
unauthenticated, signature_invalid, native_signature_invalid |
Check the credential, expiry, revocation, and provider signature. |
403 |
insufficient_scope |
Use a project credential with events:write; management tokens cannot ingest. |
409 |
idempotency_conflict, signature_replay, native_signature_replay |
Use a unique event ID or a new signature nonce. |
413 |
payload_too_large |
Reduce the event or batch body size. |
422 |
validation_failed, idempotency_key_mismatch, batch_limit_exceeded, signature_headers_incomplete, signature_timestamp_invalid, signature_timestamp_expired, signature_nonce_invalid, native_signature_headers_incomplete, native_signature_timestamp_expired |
Correct the body, header, type, timestamp, or batch size. For signed requests, provide all required signature headers and a valid, current timestamp and nonce. |
429 |
rate_limit_exceeded, billing_quota_exceeded |
For rate limits, wait for Retry-After. For quota errors, review the workspace's usage and plan in the owner interface. |
503 |
ingestion_temporarily_unavailable |
Retry with backoff and the same event IDs. For an incomplete batch receipt, resume using the same body and key as described above. |
Successful event responses include a request_id and X-Request-Id. Some error responses include a request ID, but authentication failures can return only error.code; do not assume every error has a request ID. When one is returned, log it with your application's own event ID for support and diagnosis, but never log bearer credentials or signature secrets.
10. Security and data handling
Never send passwords, password hashes, one-time codes, reset tokens, session tokens, access or refresh tokens, API key values, provider credentials, secrets, authorization headers, or cookies. This is especially important for authenticator.code_sent: report that the code was sent and include only non-sensitive delivery metadata. Use opaque application identifiers instead of email addresses or other personal data when possible.
The common intake validator replaces values beneath these exact, case-insensitive property names with [REDACTED], recursively: password, secret, token, access_token, refresh_token, api_key, authorization, and cookie. It does not reject all template-policy aliases and it does not scan arbitrary values for secret content. Revision-2 template schemas separately reject their exact forbidden field-name list when clients validate against a profile; they do not change the legacy ingestion contract or scan values. Redaction and schema validation are defense in depth, not permission to submit sensitive data.
11. Quick checklist
- Create/select the project and issue a project credential for the right environment.
- Store the
gm_project_...credential in server-side secret storage. - Use a stable unique event
id, a canonical eventtype, and a timezone-awareoccurred_at. - Send the event to
POST https://givemora.com/v1/eventswithAuthorization: Bearer ...and JSON content type. - Check both the HTTP status and the returned
routing/routing_reason. - Retry temporary failures using the same event IDs; inspect each item in a batch response.
- Never put credentials, passwords, session tokens, or one-time codes in an event.
12. Workspaces, projects, roles, and credentials
Start with an owner workspace
Sign in to your Givemora account and open the workspace you own or have been invited to. A personal account may have more than one linked workspace; use the workspace selector in Telegram or the web interface before creating a project or issuing a token. Workspaces keep member access, management tokens, destinations, usage, and projects within one authorization boundary. Projects represent individual application integrations and contain the environment-specific credentials and routing configuration.
An ordinary workspace has six roles. These examples summarize their main permission groups; the API still checks the specific permission and management-token scope for every action.
| Workspace role | Permission examples |
|---|---|
Owner |
Full workspace permission set, including workspace/member/project management, routing, destinations, credentials, webhooks, operations, incidents, delivery retry, billing, and audit access. |
Admin |
Full workspace permission set, as for Owner. |
Developer |
Manage projects, routing, destinations, credentials, webhooks, and read operations/manage incidents. |
Operator |
Read operations and incidents, retry deliveries, and toggle routing. |
Billing |
Read workspace and operations, and read/write billing controls. |
Viewer |
Read workspace, member, and activity information; manage only their own Telegram mute preferences. |
Management API authorization is checked against both the token's workspace and the actor's current workspace membership. A token never grants access to a different workspace, and removing a member or changing a role can remove access even while a token remains unexpired.
God is a platform staff role, not a workspace role. A God staff session or staff API token keeps its global platform staff access through the protected staff surface and separate platform permissions. That access does not make the user a workspace member. A workspace created for staff operations does not automatically grant workspace Owner membership, and a workspace management token remains a workspace token tied to its user and workspace, even when that user also has a God role.
Link Telegram to the intended owner account
From the signed-in dashboard, choose Link Telegram. Open the one-time link in a private Telegram chat with the bot, then send /start. The link is single-use and expires after 10 minutes. Link the Telegram identity from the private account that should own and manage the workspace. Do not share a link between users or post it in a group.
If a Telegram account is already linked, /my_id and /id show the saved profile display name; they do not reveal the numeric Telegram ID. To change your email, open Home → My profile → Change email or send /email <new-email>. Givemora sends an eight-digit code to the new address. Finish the change in the profile screen or with the registered /email_verify <code> command. Telegram command autocomplete registers underscore spellings such as /my_id and /email_verify; hyphen aliases may be accepted by the text parser, but use the registered spelling.
Some privileged actions require an approval in the Open Secure App before they can continue. Approve through a registered passkey using your device's WebAuthn user verification (for example, a device passkey with biometric or screen-lock confirmation, depending on the device), or use the supported password-and-TOTP flow. Availability depends on the account and device. Never send your password, TOTP, recovery code, or passkey secret in Telegram chat.
Choose interface and notification languages separately
Use /language or Home → Language to change the Telegram interface language. This controls translated menus and prompts. Use /event_language to set your personal Telegram event-notification language. This account-wide preference is synced to your currently linked Telegram identities; when none is saved, the configured default (en) applies. Unlinking an identity ends synchronization with the former account. When it is linked again, it adopts the event-language preference of the account it is linked to. A shared Telegram or email destination has its own event-language override in destination settings. The public documentation page selects its guide using the language selector or the Accept-Language header; appending ?lang= does not select a documentation locale.
For the same account preference through the Management API, use GET or PATCH /v1/manage/preferences/event-language with a management token issued to an Owner who is still a member of the current workspace and the projects:read or projects:write scope. GET returns {"data":{"event_locale":null,"effective_event_locale":"en"},"request_id":"…"} when no saved preference exists; the effective value follows the configured default. PATCH accepts exactly this shape: {"event_locale":"fa"}; replace fa with any supported locale. It also requires an Idempotency-Key containing 1–128 visible ASCII characters (0x21–0x7E; spaces are not allowed). Both responses include X-Request-Id and private no-store headers. Extra query or body fields, including another user's ID or an interface locale, are rejected. Repeating the same key and body replays the original response; using the key with a different body returns 409 idempotency_conflict. Receipts are scoped to the Owner and current workspace, so different Owners may reuse a key.
The event catalog localizes its own known event labels. Givemora does not translate arbitrary application summaries or payload values. If an application needs a notification summary in more than one language, send the summary explicitly for each supported language. Keep the event type and other identifiers stable across locales:
{
"id": "signup-user-123-v1",
"type": "user.signed_up",
"data": {
"summary": "A new user created an account",
"summary_translations": {
"en": "A new user created an account",
"fa": "یک کاربر حساب کاربری ساخت",
"fr": "Un nouvel utilisateur a créé un compte"
},
"user_id": "usr_123"
}
}
When the destination language has no supplied translation, the notification uses data.summary as written and identifies the source language where available. Choosing a destination language does not translate the full business payload.
Create a project and issue separate environment keys
Use Home → Projects → New project or send /new in the selected workspace. Choose the project name and slug, then open that project and issue a credential for each environment it will use. The dashboard and Telegram project screens show credential metadata; the full project credential is shown only when issued. Store it once in a server-side secret manager, and revoke and replace it if it is lost or exposed.
For a management API token, open Home → Delivery and access → Management tokens; this opens the issue form. You can also use the registered Telegram command /access_token [name]. The command /access_tokens lists token metadata; /revoke_access_token <token_id> revokes a token. The workspace menu separately exposes Issue access token, List access tokens, and Revoke access token actions. The token secret is delivered once through the private bot response; retrieve it from the secret response promptly and store it in a server-side secret manager. A repeated command does not reveal the token again.
Management tokens use the gm_owner_ prefix and can access only their bound workspace and user, subject to current membership, role, scope, and permission checks. The default token contains a baseline set of scopes. Issue separate tokens for separate integrations and request only the scopes each integration needs. Do not put a management token in an application event sender: use the gm_project_ credential for ingestion. Never send either token from browser code, mobile apps, logs, support tickets, or event payloads.
The project credential create example in Section 1 shows API issuance. A project credential is bound to its project and environment and ordinarily needs events:write; a management token cannot be used as an ingestion bearer. The management API can also create projects inside the token's workspace and issue management tokens with custom scopes. It cannot create a workspace. The first management token must come from the owner interface or linked Owner Telegram flow described above.
To create a project by API, use a workspace management token with projects:write and a current role that has the workspace projects.manage permission (Owner, Admin, or Developer). Project creation requires an idempotency key:
curl --fail-with-body --request POST 'https://givemora.com/v1/manage/projects' \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: create-orders-project-v1' \
--data '{"name":"Orders service","slug":"orders-service"}'
Copy data.id from the 201 Created response into GIVEMORA_PROJECT_ID. A matching retry replays the project response; reusing the key with a changed name or slug returns 409 idempotency_conflict.
To issue a management token for an API integration, call POST /v1/manage/access-tokens with a current user-bound management token that has projects:write and the workspace credentials.manage permission. Set only the required token scopes. This example creates a token suitable for project management and event/receipt reads:
curl --fail-with-body --request POST 'https://givemora.com/v1/manage/access-tokens' \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: issue-integration-token-v1' \
--data '{
"name":"Orders integration",
"scopes":["projects:read","projects:write","credentials:manage","events:read"],
"expires_at":null
}'
The successful 201 Created response includes the new raw token in data.token; store it immediately. Token secrets are not stored for replay, so retrying with the same key returns 409 secret_response_expired, not the token. GET /v1/manage/access-tokens lists metadata. To revoke a token, DELETE /v1/manage/access-tokens/{managementToken} requires projects:write and an Idempotency-Key.
The first project credential can be requested without an existing key: use the public first-key flow in section 1 and wait for a System God decision. It does not create a workspace or project, and the requester name is not proof of ownership. The workspace management GET and POST /v1/manage/projects/{project}/credentials operations remain available to an authorized workspace manager who already has a management token with credentials:manage; POST issues one credential for one environment. The raw token appears only in the successful response. If an acknowledged key is lost or exposed, request a replacement through the first-key flow or have an authorized manager issue one, switch and verify the sender, then revoke the old key. There is no separate rotation endpoint.
13. Read events, receipts, delivery diagnostics, and usage
Reading event records and inspecting their delivery status are separate from ingesting events. Use a workspace management token with the appropriate read scope and keep the token in a trusted server process. In the management API, {project} or {project_id} in a path means the project's ULID, not its display name or slug.
Read project events
GET /v1/manage/projects/{project}/events requires events:read. It returns a newest-first page of event records. Set limit from 1 to 50 and pass the opaque next_cursor as cursor to read the next page; keep any environment filter on every page. Event records can include the stored payload projection, so restrict access to this endpoint and avoid copying its output into ordinary logs.
export GIVEMORA_MANAGEMENT_TOKEN='gm_owner_...'
export GIVEMORA_PROJECT_ID='01J00000000000000000000000'
curl --fail-with-body --get \
"https://givemora.com/v1/manage/projects/${GIVEMORA_PROJECT_ID}/events" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--data-urlencode 'environment=production' \
--data-urlencode 'limit=20'
The response contains the event data and a next_cursor when more rows are available. Use a cursor exactly as returned; do not construct one from timestamps or event IDs. The management event list is not the same as the public event catalog and does not use a project ingestion credential.
Reconcile an accepted receipt without reading event bodies
For a single event submission, record the returned event_id alongside your own stable producer ID. For batch requests, record the returned receipt_id when present as well as each item's producer ID. A project receipt is read with GET /v1/manage/projects/{project}/event-receipts/{receipt} and events:read. It returns accepted/rejected outcome metadata without copying event payload bodies. For a batch that returned an incomplete 503 receipt, replay the exact body and key to resume processing, then use the receipt endpoint to inspect its final outcome.
export GIVEMORA_RECEIPT_ID='01J00000000000000000000000'
curl --fail-with-body \
"https://givemora.com/v1/manage/projects/${GIVEMORA_PROJECT_ID}/event-receipts/${GIVEMORA_RECEIPT_ID}" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json'
To reconcile a bounded list of accepted event IDs when you do not have a receipt ID, use POST /v1/manage/projects/{project}/event-receipts/lookup with events:read. The lookup response is bounded; use receipt IDs when you have them, and do not treat a missing result as proof that an ambiguous request was never accepted.
Inspect redacted delivery diagnostics and project routing
Use GET /v1/manage/projects/{project}/event-receipts/{receipt}/diagnostics for receipt-specific, redacted delivery diagnostics. Use GET /v1/manage/projects/{project}/destinations/{destination}/diagnostics to inspect a destination's recent delivery behavior. Both require events:read. Diagnostics are bounded and redact sensitive fields; they are intended for troubleshooting, not a raw copy of provider requests.
To inspect where project events are routed, use the project screen in the dashboard or Telegram's project routing view. The management API exposes project Telegram routes at GET /v1/manage/projects/{project}/telegram-routes; updates use PUT with projects:write and the current project-management permission. A workspace destination can serve as a configured fallback when project routing allows it. Destination scope, active state, verification, event filters, policy, and provider health all affect whether a delivery can be queued or sent.
Read aggregate usage and event analytics
GET /v1/manage/usage/events requires from and to RFC 3339 query parameters, for example ?from=2026-10-01T00%3A00%3A00Z&to=2026-11-01T00%3A00%3A00Z. GET /v1/manage/usage/events and GET /v1/manage/analytics/events use projects:read and require the workspace's current member-read permission. Usage reports consumed event units; it does not reveal the effective plan quota. Check the owner billing and usage screens for plan and quota context. Analytics are aggregate summaries, not substitutes for reading individual event rows or receipts. The Telegram workspace activity screen and /analytics_events, /usage_events, and /quota commands provide corresponding owner-facing views where your role has permission.
14. Use Telegram to manage personal event notifications
The Telegram interface supports event browsing and your own event-notification preferences. Open the bot in a private chat, choose the intended workspace with Workspaces, then open Home → Activity. The activity screen is titled Activity and monitoring and contains Events & deliveries and the muted event types view. The project and environment shown in each event detail help distinguish streams that share the same event type.
Open an event from a notification
When a supported personal notification includes View details, tap it to open the event detail page in your private chat with the bot. Details are looked up again when you open them and are available only while the event remains retained and your current workspace access allows it. If the button has expired or access changed, return to the project event explorer and select the event again. The detail view includes workspace, project (including slug when available), environment, event type, source when supplied, severity, time, and event ID. The content section shows a bounded event projection with sensitive fields recognized by the redaction rules masked. Redaction cannot identify every secret in free text; never include credentials or other secrets in events.
Mute and re-enable one event type for yourself
From an event notification, choose Mute similar events to mute that exact project and event type for your own Telegram alerts. Or open Home → Activity → Muted event types to see your current list and re-enable a type. The mute is private to your user, current workspace, project, and exact event type; it applies across that event type's environments and sources. It does not change project routing, other users' notifications, or the event record.
The command forms are:
/event_ops mutes
/event_ops mute <project-slug> <event-type>
/event_ops unmute <project-slug> <event-type>
For example, an event type is billing.invoice_paid; preserve it exactly as supplied. A mute applies only to your private Telegram notification preference. Project rules, notification pause, destination filters, and other members' preferences are separate controls.
Browse the event catalog and switch language
Use Home → Activity → Event catalog to browse the recommended event types, or call /event_catalog. The catalog localizes known standard labels for the selected interface locale. Event types and project slugs remain identifiers and should be copied exactly. Use /language for interface menus, /event_language for your personal Telegram alerts, and destination settings for a shared Telegram or email destination's event language; these controls are separate. Application-written free text uses the supplied summary and is not machine-translated by the bot.
15. Run reports, create exports, and schedule delivery
Saved reports capture filters and an explicit allowlist of payload fields. Report definitions, run results, and exports are scoped to the current workspace and re-authorized on each request. Create a definition as a current workspace Owner or Admin with the management token scope projects:write. Start runs and read results with projects:read plus the workspace's current operations-read permission. A management token alone does not bypass the user's current role.
Create a small saved report
This example creates a workspace report with a production filter and one allowed event data field. The payload allowlist is deliberately narrow. A report's scope can be workspace or project; a project report also supplies project_id. Private visibility is the default; use visibility: "workspace" only when other authorized workspace members should see the definition. Keep each idempotency key stable when retrying the same request and use a new key only for a changed intended definition.
export GIVEMORA_REPORT_ID=''
export GIVEMORA_IDEMPOTENCY_KEY='create-report-orders-v1'
curl --fail-with-body --request POST 'https://givemora.com/v1/manage/reports' \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: ${GIVEMORA_IDEMPOTENCY_KEY}" \
--data '{
"name": "Production invoice events",
"scope": "workspace",
"visibility": "private",
"definition": {
"filters": {"environment": "production", "event_types": ["billing.invoice_paid"]},
"payload_allowlist": ["data.invoice_id"]
}
}'
Copy data.id from the 201 Created response into GIVEMORA_REPORT_ID. The filters may include environment, event_types, severities, destination_id, correlation_id, tags, and payload; see the management OpenAPI source in the repository for exact filter validation. Payload paths must be explicit and permitted by the report payload-path policy.
You can preview a definition before queuing a saved run. POST /v1/manage/reports/{report}/preview accepts only the from and to RFC 3339 timestamps; to must be later than from and the window cannot exceed 31 days. The route requires projects:read and operations-read access, and returns a bounded, redacted result using received_at as its time basis. It does not create a saved run:
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/preview" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"from":"2026-10-01T00:00:00Z","to":"2026-10-02T00:00:00Z"}'
Start a bounded run, poll it, and read its result pages
Start a run with an RFC 3339 UTC window no longer than 31 days and a new stable Idempotency-Key. Matching retries return the existing run. The 202 Accepted response gives data.id and the current status; run processing is asynchronous.
export GIVEMORA_RUN_ID=''
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/runs" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: run-orders-2026-10-01-2026-10-02-v1' \
--data '{"from":"2026-10-01T00:00:00Z","to":"2026-10-02T00:00:00Z"}'
Copy the returned data.id into GIVEMORA_RUN_ID before polling. Choose a date window that covers the event time you expect to report on, and make the report filters and payload_allowlist match fields actually present in those events; a valid run can return no matching rows. Poll the run with GET /v1/manage/reports/{report}/runs/{run} using the same workspace management token. The response includes data.status, counters, last_error_code, and, when ready, the first data.rows page. Use the returned integer next_cursor and a limit from 1 to 50 to fetch later pages; stop when has_more is false. A run can complete with a lower-bound count when processing is bounded; check count_kind, candidate_lower_bound, evaluated_count, and skipped_count before interpreting totals.
curl --fail-with-body \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/runs/${GIVEMORA_RUN_ID}?limit=50" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json'
If a queued or running report run should stop, cancel it explicitly. Run cancellation requires confirmation in the JSON body and an idempotency key. It requires projects:read and the current workspace operations-read authorization:
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/runs/${GIVEMORA_RUN_ID}/cancel" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: cancel-orders-run-v1' \
--data '{"confirm":true}'
Create, poll, and download an export
Create an export only after the run has completed. Formats are json, csv, csv_safe, and pdf. The response is asynchronous; poll GET /v1/manage/reports/{report}/runs/{run}/exports/{artifact} until it is ready or reaches a terminal error. A ready response supplies a short-lived download_url (valid for up to five minutes). Fetch it promptly with the same management bearer token; the server rechecks the workspace and current authorization while serving the file. Do not persist or share the URL as a permanent link.
export GIVEMORA_EXPORT_ID=''
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/runs/${GIVEMORA_RUN_ID}/exports" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: export-orders-run-v1' \
--data '{"format":"csv_safe"}'
curl --fail-with-body \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/runs/${GIVEMORA_RUN_ID}/exports/${GIVEMORA_EXPORT_ID}" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json'
curl --fail-with-body "$GIVEMORA_EXPORT_DOWNLOAD_URL" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--output report.csv
Copy the export data.id from the first command into GIVEMORA_EXPORT_ID. After polling shows that the export is ready, copy data.download_url into GIVEMORA_EXPORT_DOWNLOAD_URL and download it before the five-minute expiry. Treat the URL as a secret. Export requests can be rejected by storage or quota limits; use the returned error code and request ID where present, and do not endlessly repeat an export with a new key when the outcome is ambiguous.
If a queued export should stop, cancel it with a separate stable idempotency key and the same projects:read/operations-read authorization:
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/runs/${GIVEMORA_RUN_ID}/exports/${GIVEMORA_EXPORT_ID}/cancel" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Idempotency-Key: cancel-orders-export-v1'
Schedule a report delivery
Create a schedule with POST /v1/manage/reports/{report}/schedules and an idempotency key. Use an IANA timezone, local HH:MM, a window_days from 1 to 31, and one to 20 unique destination ULIDs that are active, verified, and eligible. A daily schedule uses weekday: null; a weekly schedule uses ISO weekday 1–7. The destination IDs come from the workspace or project destination list. Do not put raw email addresses, Telegram chat IDs, or destination secrets in the request.
curl --fail-with-body --request POST \
"https://givemora.com/v1/manage/reports/${GIVEMORA_REPORT_ID}/schedules" \
--header "Authorization: Bearer ${GIVEMORA_MANAGEMENT_TOKEN}" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: daily-orders-report-v1' \
--data '{
"frequency": "daily",
"timezone": "Europe/Paris",
"local_time": "08:30",
"weekday": null,
"window_days": 1,
"destination_ids": ["01J00000000000000000000000"],
"presentation_locale": "en"
}'
Replace the example destination ULID with an actual configured destination available to the report. Schedules support daily and weekly; use weekday for the weekly day. Read GET /v1/manage/reports/{report}/schedules/{schedule} for current status and GET /v1/manage/reports/{report}/schedules/{schedule}/history for occurrences, skipped runs, and delivery errors. Update with PATCH /v1/manage/reports/{report}/schedules/{schedule}; send the current expected_revision, validated schedule fields, and an Idempotency-Key. The /pause and /resume actions also require the current revision and an idempotency key; /disable additionally requires confirm: true. If a destination is paused, unverified, removed, or no longer authorized, the schedule may become stale or unauthorized; fix the destination or permissions before resuming it.
16. Choose an SDK or call the HTTP API directly
The event endpoints are ordinary HTTPS JSON APIs. You can use them directly from any server language without installing a Givemora package. The canonical public HTTP reference is the event OpenAPI document; the public management API contract is not published at that URL. The repository contains separate management and staff OpenAPI source files for developers with repository access.
SDK availability
The repository currently includes PHP, Python, Go, and TypeScript SDK previews. These are private repository previews; they are not published to public package registries and are not represented as supported registry installs. Do not assume that composer require, pip install, go get, or npm install from a public registry will find them. Review the language-specific README and package metadata in the repository before building from a local checkout or artifact.
The SDK references are repository paths, not public site URLs:
| Language | Repository reference | Scope |
|---|---|---|
| PHP | sdk/php/README.md |
Event sending, batch outbox, management event reads, typed pages. |
| Python | sdk/python/README.md |
Event sending, batches, durable outboxes, management event reads and receipt diagnostics. |
| Go | sdk/go/README.md |
Event sending, batch handling, file outbox, management event pages. |
| TypeScript | sdk/typescript/README.md |
Event sending, batch outbox and result inspection. |
SDK coverage is not identical across languages. Check the relevant README and contract fixtures before depending on a method. None of these SDKs replaces the public HTTP contract or grants management permissions by itself.
Direct HTTP fallback
For a small server integration, keep the stable event ID in application storage before sending. Use the project credential only as a server-side bearer secret, send the same JSON body when retrying, and inspect both the HTTP status and receipt fields. This minimal Python example uses only the standard library:
import json
import os
import urllib.request
event = {
"id": "signup-user-123-v1",
"type": "user.signed_up",
"severity": "info",
"data": {"summary": "A user created an account", "user_id": "usr_123"},
}
body = json.dumps(event, separators=(",", ":")).encode("utf-8")
request = urllib.request.Request(
"https://givemora.com/v1/events",
data=body,
headers={
"Authorization": f"Bearer {os.environ['GIVEMORA_PROJECT_KEY']}",
"Accept": "application/json",
"Content-Type": "application/json",
"Idempotency-Key": event["id"],
},
method="POST",
)
with urllib.request.urlopen(request, timeout=10) as response:
receipt = json.load(response)
print(response.status, receipt["event_id"], receipt["routing"])
Handle urllib.error.HTTPError and transport timeouts in the calling application. On an ambiguous result, retry the unchanged event with the same ID and idempotency key; do not generate a new ID for the same logical event.
Durable outbox behavior
If an application must survive restarts or temporary network failures, persist an outbox before attempting delivery. Keep the exact event body, stable IDs, ordering, and idempotency key until a receipt confirms the result. Store credentials outside the outbox and keep the outbox file or database private. A durable batch outbox should retain the exact ordered request and key across ambiguous attempts, record per-item outcomes after settlement, and stop automatic replay when the server's idempotency horizon has expired. Check the language SDK's documented bounds, retention behavior, and recovery methods; batch order is significant, and replaying an altered batch under the same key is a conflict.
Version 2: asynchronous event ingestion
Version 2 is a separate opt-in from the existing v1 endpoints and SDK methods. Its API reference is the v2 event OpenAPI document. Use the same current project environment key with the events:write scope as a Bearer credential for both submissions and polls; do not use a management or staff token.
| Operation | HTTP API | SDK method |
|---|---|---|
| Submit one event | POST /v2/events |
PHP/TypeScript submit; Python submit; Go SubmitEvent |
| Submit an ordered batch | POST /v2/events/batch |
PHP/TypeScript submitBatch; Python submit_batch; Go SubmitBatchEvents |
| Read current status for one accepted event | GET /v2/event-submissions/{submission} |
getSubmission, get_submission, or GetSubmission |
| Read a page of batch receipt items | GET /v2/event-submission-batches/{receipt}?limit=100 |
getSubmissionBatch, get_submission_batch, or GetSubmissionBatch |
Every v2 POST requires an Idempotency-Key of 1–128 visible ASCII characters. For a single event, a non-null id must equal that key; if id is absent or null, the key supplies it. For a batch, keep each non-null event id as its per-event producer key and use a separate batch Idempotency-Key. Generate and save IDs and keys once; SDKs prepare and serialize the request once and reuse the same body, key, and batch order on retries. V2 uses separate idempotency namespaces from v1. A changed batch body—including changed whitespace or object-property order—conflicts with the original batch key.
curl --fail-with-body --request POST 'https://givemora.com/v2/events' \
--header "Authorization: Bearer ${GIVEMORA_PROJECT_KEY}" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: signup-user-123-v1' \
--data '{"id":"signup-user-123-v1","type":"user.signed_up","severity":"info","data":{"summary":"A user signed up"}}'
HTTP 202 confirms durable acceptance, not completed routing or provider delivery. A single-event response includes a submission_id with routing initially pending; poll it with GET /v2/event-submissions/{submission} to read current payload-free routing status. A batch 202 contains ordered per-item receipt outcomes; poll accepted items by their submission_id for current routing. The batch receipt is an immutable processing snapshot and may still show pending after an item has routed. Neither acceptance nor routing status proves delivery by Telegram or another provider.
In poll responses, routing_status is the submission-processing lifecycle (pending, routed, blocked, or failed); routing is a separate nullable, open-ended routing decision, so clients must accept new string values for it. For example, {"routing_status":"routed","routing":"filtered"} means processing finished and the routing decision is filtered. routing_reason and sanitized routing_explain may provide payload-free context. A successful single-event POST acknowledgement still starts with both fields set to pending; later poll values are independent.
If a batch POST returns 503 with status: "incomplete", processing may already have accepted a prefix. Keep the returned receipt_id, poll GET /v2/event-submission-batches/{receipt}?limit=100 (following next_cursor) with the same project credential, and preserve the accepted-prefix results. If the receipt now has status: "completed", read every receipt page, preserve the ordered item results, and use GET /v2/event-submissions/{submission} for each accepted submission_id to read current routing; do not POST the batch again. If it is still incomplete, wait for Retry-After and retry only the exact original ordered body with the same batch key. Do not assume rollback or construct a new body. Honor Retry-After within a bounded caller deadline and before the receipt/idempotency horizon expires; for an outbox, if the wait plus required polling and retry will not fit the current drain deadline, leave the record for a later drain instead of retrying early. A 404 or 410 while polling means the receipt/submission is unavailable or expired; stop automatic re-ingestion and reconcile manually rather than generating a new key.
Durable v2 outboxes
The four private-preview SDKs provide separate v2 outboxes; they do not reuse the v1 outbox format. Their default capacity is 1,000 records and 10 MiB combined serialized state. The default per-event limit is 256 KiB; batches are limited to 100 items and 5 MiB. Deployments can set tighter limits. When capacity is full, enqueue fails before HTTP rather than evicting pending or unknown work. A terminal record can be removed explicitly after review with acknowledge.
An outbox persists the exact already-redacted request body, fingerprint, stable key, item order and origin binding before the first HTTP attempt. It does not persist credentials, signing secrets, nonces or authorization headers. Each record is bound to the normalized API origin and a fingerprint of the project credential used when it was created; drain it only with that same origin and credential. If either changes, the outbox rejects the drain; do not retry that record with a different origin or credential. The first attempt establishes the finite idempotency horizon; time spent queued before a first attempt does not consume it. SDK retention options accept 1–30 days. Set the SDK horizon no longer than the server's configured receipt retention; the server default is 30 days but a deployment may use less. After an ambiguous outcome reaches expiry, the outbox records an unknown/manual-review state and does not silently create a new key or replay the request.
After a batch 503, the outbox polls the saved receipt before any POST retry. If the receipt now has status: "completed", it reads every receipt page, retains the ordered results, and uses GET /v2/event-submissions/{submission} for accepted submission IDs without resubmitting the batch. It retries the exact original body and key only if the receipt is still incomplete and after Retry-After. After a completed batch 202, it uses GET /v2/event-submissions/{submission} for accepted submission IDs and never resubmits that batch. Use the SDK's bounded drain methods; do not hold outbox locks or transactions over HTTP.
| Language | Direct v2 methods | Separate v2 outbox and helpers | Signed-ingestion opt-in | Repository guide |
|---|---|---|---|---|
| PHP | submit, submitBatch, getSubmission, getSubmissionBatch |
AsyncJsonFileOutbox; enqueueSubmission, enqueueSubmissionBatch, drainSubmissions |
withSignedIngestion() |
sdk/php/README.md |
| Python | submit, submit_batch, get_submission, get_submission_batch |
AsyncFileOutbox; enqueue_submission, enqueue_submission_batch, drain_submissions |
with_signed_ingestion() |
sdk/python/README.md |
| Go | SubmitEvent, SubmitBatchEvents, GetSubmission, GetSubmissionBatch |
AsyncFileOutbox; EnqueueSubmission, EnqueueSubmissionBatch, DrainSubmissions / DrainSubmissionsContext |
WithSignedIngestion(true) |
sdk/go/README.md |
| TypeScript | submit, submitBatch, getSubmission, getSubmissionBatch |
IndexedDBAsyncOutbox in browsers; AsyncJsonFileOutbox from @givemora/events/node-outbox in Node; enqueueSubmission, enqueueSubmissionBatch, drainSubmissions |
withSignedIngestion() |
sdk/typescript/README.md |
These SDKs are private repository previews, not public registry packages. Check the language README for local package setup and adapter-specific bounds. Keep v1 calls and outboxes on their existing methods and storage; choose v2 methods explicitly.
Optional request signing
Signing is opt-in and uses the same literal project Bearer key as the HMAC key; it does not require a second secret. Each signed ingestion POST gets a fresh Unix-seconds X-Givemora-Timestamp, fresh 32-character lowercase-hex X-Givemora-Nonce, and X-Givemora-Signature header. Compute the signature over the exact request bytes:
sha256=lowercase_hex(HMAC-SHA256(project_key, timestamp + "." + nonce + "." + exact_raw_request_body))
The SDK serializes/redacts before signing and uses those same bytes for the request body. A retry keeps the body and idempotency key but creates a fresh timestamp, nonce and signature. GET polls are not signed by this option. Do not store signature material in the outbox. The SDK JSON signing option does not implement CloudEvents HTTP binary framing; follow the OpenAPI signing contract for that mode.
17. Advanced APIs and authorization boundaries
The owner interface and Telegram menus are the easiest way to configure day-to-day operations. The management API supports additional workflows. Route names and scope examples below are for orientation; the repository's source OpenAPI documents and current product responses remain authoritative. The public event OpenAPI URL documents event ingestion/catalog operations. Management and staff OpenAPI files are repository references only, not public download routes.
| Capability | Typical management route or workflow | Access boundary |
|---|---|---|
| Project events, receipts, and diagnostics | /v1/manage/projects/{project}/events, /event-receipts, and diagnostics paths |
Workspace management token with events:read; current member role is also checked. |
| Destinations and outbound webhooks | /v1/manage/destinations, /projects/{project}/destinations, and outgoing-webhook management routes |
Usually projects:read to inspect and projects:write plus current Owner/Admin project-management permission to change. Verify email destinations before enabling delivery. |
| Incidents and on-call | /v1/manage/incidents and on-call configuration routes |
Incident reads/actions use incidents:read/incidents:write; on-call configuration reads use incidents:read and operations-read access, while on-call writes use on_call:write and routing-management access. |
| Event schemas and quarantine | /v1/manage/projects/{project}/schemas and /schemas/quarantine |
projects:read to inspect and projects:write to register or activate versions; quarantine lists metadata without payload bodies. |
| Routing rules and versions | Project event-rule/routing management paths | Read operations require project read permission; rule simulation is a preview exception requiring projects:read, events:read, and operations-read access. Mutations require project write and applicable current project-management authorization. Use previews and version checks before activation. |
| Projection replay and resend | /v1/manage/projects/{project}/event-replays |
events:read for preview/status and events:replay for starting, resuming, or cancelling a replay. A resend linked to a replay can also require deliveries:resend; it is a separate delivery action. |
| Event archives and retention | /v1/manage/projects/{project}/event-archives and event retention-hold paths |
Archive operations require events:read; retention policy changes use project read/write scopes and current authorization. Downloads are temporary and authorized at retrieval. |
| Privacy requests and audit | /v1/manage/privacy-requests, /v1/manage/audit-events |
Privacy requests are workspace-owner operations. List/read/preview routes require projects:read and applicable current member-read access; create and mutation routes require projects:write and applicable project-management access. Authenticated audit reads require audit:read. Sensitive exports are private and are checked again when downloaded. |
| Service principals | /v1/manage/projects/{project}/service-principals |
principals:read for reads and principals:write for mutations, plus the separate workspace credentials:manage permission; ownership, rotation, revocation, and history operations recheck current authorization. |
| Organization sign-in and provisioning | Organization identity-provider, policy, and SCIM routes | Identity-provider management requires an Organization Owner, a token workspace linked to that organization, and the required projects:read/projects:write scope; do not substitute generic workspace Admin. SCIM tokens have a separate organization scope and lifecycle. Never place SCIM or identity-provider secrets in event payloads. |
| Platform staff controls | Staff API routes and God-only Telegram screens | Separate staff identity, platform permissions, and where required fresh Step-Up. A workspace management token is not a staff credential. |
For a management token, include only the read/write scopes required for its integration and keep it workspace-bound. Some write routes require both a management scope and a current Owner/Admin role with the associated workspace permission. 401 indicates missing or invalid authentication; 403 indicates scope or permission denial; 404 can intentionally hide a resource the actor cannot access. Do not broaden a token's scopes to work around a role denial.
Platform staff endpoints use a different authorization system. Do not send a God staff token as a project or workspace management credential. Protected staff mutations may require a current staff permission and fresh Step-Up; preserve those checks and use the staff API contract only for an explicitly authorized staff workflow.
18. Agent handoff and troubleshooting
An engineer or coding agent can implement a sender from this guide without access to the private repository: use the public event API, a project credential issued by the workspace owner, and the event examples above. Repository files are useful only when the integration needs the preview SDKs or additional management/staff contract details.
Handoff template
Give an implementation agent the smallest useful, non-secret contract:
Service: https://givemora.com
Project ID: <project ULID; keep private to authorized maintainers>
Environment: <development | staging | production>
Ingestion endpoint: POST /v1/events
Credential injection: secret manager variable GIVEMORA_PROJECT_KEY
Event type: <canonical event type>
Stable producer ID: <format and uniqueness rule>
Payload fields: <approved non-sensitive field names>
Retry policy: <timeout, backoff, Retry-After handling, idempotency horizon>
Acceptance: HTTP 202, persist event_id/receipt_id and routing result
Readback owner: <authorized service/operator with events:read>
Never store in source or send to agent: token values, customer data, raw provider payloads
Provide synthetic project IDs and sample payloads in implementation tasks. Do not paste live credentials, customer identifiers, event dumps, authorization headers, webhook signature secrets, cookies, or one-time codes into prompts or tickets. The owner or an authorized maintainer provisions the secret in the deployment environment outside source control.
Troubleshooting sequence
- Confirm the base URL, method, JSON encoding, content type, project credential, and that the key belongs to the intended project/environment.
- For
401, verify the credential secret and revocation state. For403, checkevents:writeon the project key; a management token is not an ingestion key. - For
422, inspect the safe validation error and correct the event envelope, timestamp, type, body size, signature headers, or batch item count. - For
409 idempotency_conflict, compare the stable ID/key and original body. A different logical event needs a new ID; the same event must keep its original body. - For
429, wait forRetry-Afterbefore retrying. Rate limits and event usage quotas are separate; usage totals do not reveal the current plan quota. - For a
503single event, retry with the same event ID. For an incomplete batch receipt, replay the exact batch body and key, then inspect the receipt. - For
202with routingqueued, inspect the receipt and destination diagnostics if delivery does not arrive. Queued means asynchronous processing started; it does not guarantee provider delivery. - For direct webhooks, verify whether the request has a bearer project credential and which signature scheme was selected. When a native signature header is present, its secret must be the same project credential; otherwise verify upstream and forward a normalized event.
When escalating, provide the HTTP status, safe error.code, returned request_id if present, receipt ID, event ID, project ID, environment, and approximate UTC time. Share no token values or raw event payloads. Keep event ID and receipt ID distinct: the event ID identifies a stored event; a receipt groups an acceptance outcome or batch replay.