Project Event Ingestion Guide

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

1. Set up a project credential

Create or select a project in the Givemora owner workspace. Issue a project credential for each environment the application uses. 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 the events:write scope 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 when it is issued. Do not put it in browser JavaScript, a mobile app, source control, event payloads, or logs. If it is lost or exposed, revoke it and issue a replacement.

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,
  "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. The batch endpoint uses each event's id for deduplication; do not rely on an Idempotency-Key request header for a batch.

4. Event body reference

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. Recognized sensitive key names are redacted during validation, but 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.

6. Event intake options

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.

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, and synthetic_check. 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.

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 an id on every item. Retry the complete batch after a timeout or transient error; Givemora deduplicates events that were already accepted. This is especially important if a service interruption occurs after some batch items have been processed.

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:

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.

Error responses include an error.code, a request_id, and, when applicable, details. Log the request ID 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.

Givemora recognizes and redacts sensitive key names such as password, secret, token, access_token, refresh_token, api_key, authorization, and cookie, including nested values. Redaction is a defense in depth, not permission to submit sensitive data.

11. Quick checklist

1. Create/select the project and issue a project credential for the right environment.
2. Store the gm_project_... credential in server-side secret storage.
3. Use a stable unique event id, a canonical event type, and a timezone-aware occurred_at.
4. Send the event to POST https://givemora.com/v1/events with Authorization: Bearer ... and JSON content type.
5. Check both the HTTP status and the returned routing / routing_reason.
6. Retry temporary failures using the same event IDs; inspect each item in a batch response.
7. Never put credentials, passwords, session tokens, or one-time codes in an event.