Backend Events

Send durable server-side product events to SafetyKit.

Beta.

SafetyKit uses backend events to understand meaningful product actions such as account creation, account updates, user-to-user contact, content uploads, product listing changes, user reports, and moderation decisions. Send events from your backend after the action has happened in your system. Do not send backend events directly from a browser or mobile client.

Use the Events API reference for the full request schema, SDK examples, and response fields.

Quick Start

Send one event, or an ordered batch of events, to:

POST https://api.safetykit.com/v1/events
Authorization: Bearer <SAFETYKIT_API_KEY>
Content-Type: application/json

For a faster response, send the same request body to POST https://api.safetykit.com/v1/async/events. SafetyKit returns after the events are queued, before they have been fully ingested.

Single event:

{
  "type": "user_contact",
  "event_name": "message_sent",
  "user_id": "user_123",
  "target_user_id": "user_456",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content_id": "message_abc123",
  "content": [
    {
      "type": "text",
      "key": "body",
      "text": "Hey, is this still available?"
    }
  ],
  "metadata": {
    "conversation_id": "conversation_789",
    "channel": "marketplace_dm"
  },
  "client_info": {
    "ip": "203.0.113.7"
  }
}

Response:

{
  "status": "ok",
  "event_id": "01KSR4C8JN1SA9X63T6P368K6W"
}

Batch event request:

[
  {
    "type": "update_account",
    "event_name": "profile_updated",
    "user_id": "user_123",
    "timestamp": "2026-05-21T00:15:10.000Z",
    "metadata": {
      "changed_fields": ["bio"]
    }
  },
  {
    "type": "user_contact",
    "event_name": "message_sent",
    "user_id": "user_123",
    "target_user_id": "user_456",
    "timestamp": "2026-05-21T00:15:15.000Z",
    "content_id": "message_abc123"
  }
]

Response:

{
  "status": "ok",
  "event_ids": ["01KSR4C8JN1SA9X63T6P368K6W", "01KSR4CB1MFVX1TAYM46YQXZ3E"]
}

SafetyKit ingests every event in a batch before returning a response.

Event Shape

Every event is a JSON object:

{
  "type": "user_contact",
  "event_name": "message_sent",
  "user_id": "user_123",
  "target_user_id": "user_456",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content_id": "message_abc123",
  "content": [],
  "resources_used": [],
  "metadata": {}
}

Required base fields:

type: one of user_contact, content_uploaded, product_changed, create_account, update_account, user_report, or moderation_decision
event_name: a stable, low-cardinality snake_case name for the product action
timestamp: the time the event occurred in your system, as an ISO 8601 datetime string
user_id: your canonical stable identifier for the user or account performing the action. For user_report, this is the reporter. Do not send user_id for moderation_decision.

Use stable event names like message_sent or profile_updated. Put dynamic values in typed fields, content, resources_used, or metadata.

Common optional fields:

target_user_id: the other user in a user-to-user interaction, the user being reported for user_report, or the user being moderated for moderation_decision
target_content_id: for user_report or moderation_decision, your stable identifier for the content being reported or moderated
content_id: your stable identifier for the content involved in the event, such as a message, listing, page, post, profile, uploaded media item, or report object
content: user-authored or user-uploaded content SafetyKit should compare or analyze
resources_used: reusable identifiers or real-world resources associated with the event
metadata: freeform non-PII product context for filtering, segmentation, debugging, and investigation
client_info: client context observed by your backend for the user action that triggered the event, such as the client IP address

Include content_id whenever you send content and your system has a stable ID for that content. SafetyKit stores this alongside the computed content hash so you can later report, search, join, or reconcile the content in your system.

Event Types

`user_contact`

Use when one user contacts, transacts with, or otherwise interacts with another user.

Required fields:

user_id
target_user_id

Recommended fields:

content, if the interaction includes a message or user-authored note
content_id, if the interaction includes a message or other stable content object
metadata, for conversation IDs, transaction IDs, channel names, or similar context
client_info, for the IP address your backend observed for the interaction

Example:

{
  "type": "user_contact",
  "event_name": "message_sent",
  "user_id": "sender_123",
  "target_user_id": "recipient_456",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content_id": "message_abc123",
  "content": [
    {
      "type": "text",
      "key": "body",
      "text": "Hey, is this still available?"
    }
  ],
  "metadata": {
    "conversation_id": "conversation_789"
  }
}

`create_account`

Use when a user creates an account.

Required fields:

user_id

Recommended fields:

resources_used, for signup emails, phones, names, addresses, URLs, or social handles
content, for public bio or profile text
content_id, if you include profile, bio, media, or other content with a stable ID in your system
metadata, for signup source, cohort, or other event-local context
client_info, for the IP address your backend observed for the signup

`update_account`

Use when a user updates account or profile information.

Required fields:

user_id

Recommended fields:

resources_used, for changed emails, phones, social handles, addresses, URLs, or payment identifiers
content, for changed public bio or profile text
content_id, if the changed profile, bio, media, or other content has a stable ID in your system
metadata, for changed field names, visibility state, or other event-local context
client_info, for the IP address your backend observed for the change

Example:

{
  "type": "update_account",
  "event_name": "profile_updated",
  "user_id": "user_123",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content_id": "profile_user_123",
  "content": [
    {
      "type": "text",
      "key": "bio",
      "text": "Independent designer making limited-run products."
    }
  ],
  "metadata": {
    "changed_fields": ["bio"],
    "profile_visibility": "public"
  },
  "client_info": {
    "ip": "203.0.113.7"
  }
}

`content_uploaded`

Use when a user posts, uploads, publishes, edits, or replaces content.

Required fields:

user_id
content

Recommended fields:

content_id, for the listing, post, page, profile, upload, media item, or other content object being added or changed
metadata, for listing IDs, post IDs, visibility state, category, or similar product context
client_info, for the IP address your backend observed for the upload

Example:

{
  "type": "content_uploaded",
  "event_name": "project_story_updated",
  "user_id": "creator_456",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content_id": "project_789_story",
  "content": [
    {
      "type": "text",
      "key": "project_story",
      "text": "We are building a new limited edition product."
    },
    {
      "type": "image",
      "key": "hero_image",
      "source": {
        "type": "url",
        "url": "https://cdn.example.com/project/hero.jpg"
      }
    }
  ],
  "metadata": {
    "project_id": "project_789",
    "visibility": "public"
  }
}

`product_changed`

Use when a product listing is created or updated. This is content_uploaded plus typed product commerce fields.

Required fields:

user_id
content
product, with price (amount as a decimal string and currency as an ISO 4217 code), optional discounted_price, and optional shipping_info (ships_from string and ships_to array of strings)

event_name must be one of product_created or product_updated.

When a product_changed event is accepted, SafetyKit sends an event.product_changed webhook containing the full original event.

Example:

{
  "type": "product_changed",
  "event_name": "product_created",
  "user_id": "seller_123",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content_id": "product_abc123",
  "content": [
    {
      "type": "text",
      "key": "description",
      "text": "Vintage leather jacket"
    },
    {
      "type": "image",
      "key": "primary_photo",
      "source": {
        "type": "url",
        "url": "https://cdn.example.com/products/abc123.jpg"
      }
    }
  ],
  "product": {
    "price": {
      "amount": "500.00",
      "currency": "usd"
    },
    "discounted_price": {
      "amount": "49.99",
      "currency": "usd"
    },
    "shipping_info": {
      "ships_from": "us",
      "ships_to": ["us", "ca"]
    }
  },
  "metadata": {
    "category": "apparel"
  }
}

`user_report`

Use when a user reports another user or a piece of content.

Required fields:

user_id
labels

Recommended fields:

target_user_id, for the user being reported
target_content_id, for the content being reported
content_id, for your stable identifier for the report object
content, for report text, screenshots, evidence, or other explanatory content SafetyKit should compare or analyze
metadata, for report surface, source, queue, or other product context

A report should include target_user_id, target_content_id, or both. Prefer both when the report is about a content item and you know the user associated with that content.

Example:

{
  "type": "user_report",
  "event_name": "content_report_submitted",
  "user_id": "reporter_789",
  "target_user_id": "seller_456",
  "target_content_id": "listing_abc123",
  "labels": ["spam"],
  "content_id": "report_abc123",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "content": [
    {
      "type": "text",
      "key": "report_reason",
      "text": "This listing looks like spam."
    }
  ],
  "metadata": {
    "report_surface": "listing_page"
  }
}

SafetyKit stores the canonical report event and records one label row per report label.

`moderation_decision`

Use when an automated enforcement system or manual review workflow labels or decides on a user or piece of content.

Required fields:

source_type
source_id
labels

Recommended fields:

target_user_id, for the user being moderated
target_content_id, for the content being moderated
content_id, for your stable identifier for the decision object
content, for review notes, decision rationale, evidence, or other explanatory content SafetyKit should compare or analyze
metadata, for outcome, confidence, queue, rule, model version, or other product context

A moderation decision should include target_user_id, target_content_id, or both. Do not include user_id; use source_type and source_id for attribution.

source_type is the source category for the decision. Supported values:

human_moderator: a human reviewer in your moderation workflow
expert_labeler: an expert human labeler or specialist reviewer
automation: an automated model, rules engine, or enforcement workflow
vendor: an external review or moderation provider

source_id is the stable identifier within source_type. Examples: moderator@example.com or 550e8400-e29b-41d4-a716-446655440000 for expert_labeler or human_moderator, automated_review_v2026_06_04 for automation, or <vendor_name>-v2.1 for vendor.

Example:

{
  "type": "moderation_decision",
  "event_name": "content_moderation_decided",
  "source_type": "automation",
  "source_id": "automated_review_v2026_06_04",
  "target_user_id": "seller_456",
  "target_content_id": "listing_abc123",
  "labels": ["spam"],
  "content_id": "decision_abc123",
  "timestamp": "2026-05-21T00:15:15.000Z",
  "metadata": {
    "decision": "remove",
    "confidence": "high"
  }
}

Content

Use content for user-authored or user-uploaded content SafetyKit should compare or analyze.

Text part:

{
  "type": "text",
  "key": "body",
  "text": "Hey, is this still available?"
}

Image part:

{
  "type": "image",
  "key": "profile_photo",
  "source": {
    "type": "url",
    "url": "https://cdn.example.com/images/profile.jpg"
  }
}

Guidelines:

Split structured content into meaningful parts.
Use stable key values such as body, title, description, bio, or primary_photo.
Include the top-level content_id whenever the content has a stable ID in your system.
Do not add IDs or timestamps to text just to make it unique.
Send original user-authored text rather than rendered HTML when possible.
Send canonical media URLs when available.

Resources

Use resources_used for reusable identifiers associated with the event.

[
  {
    "type": "email",
    "value": "user@example.com"
  },
  {
    "type": "phone",
    "value": "+12069406843"
  },
  {
    "type": "url",
    "value": "https://example.com/profile/user_123"
  }
]

Common resource types include email, phone, name, address, url, facebook, instagram, x, tiktok, youtube, linkedin, and payment_instrument.

Guidelines:

Send values exactly as your backend receives or stores them.
Prefer E.164 phone numbers if your system already has them.
Prefer canonical URLs if your system already has them.
Do not put multiple resources in one string.
Do not duplicate the same value in both resources_used and metadata.

Metadata

Use metadata for freeform non-PII product context for filtering, segmentation, debugging, and investigation.

{
  "conversation_id": "conversation_789",
  "channel": "marketplace_dm",
  "is_first_message": true,
  "message_count_24h": 12
}

Metadata values may be strings, numbers, booleans, or arrays of strings, numbers, or booleans. Metadata keys should be stable snake_case strings.

Do not put raw PII, message bodies, bios, addresses, image URLs, or reusable identifiers in metadata. Use content or resources_used. Put the client IP address in client_info.

Client Info

Use client_info for client context observed by your backend for the user action that triggered the event. Every event type accepts it.

{
  "ip": "203.0.113.7"
}

ip: the IP address observed by your backend for the client that triggered the event

SafetyKit links events sharing an IP address, so sending client_info.ip on signups, account changes, contacts, and uploads helps surface coordinated activity such as mass account creation or ban evasion.

Guidelines:

Send the address your backend attributes to the end client, such as the connecting address after resolving trusted proxy headers.
Both IPv4 and IPv6 addresses are accepted.
Send client_info.ip on every event where your backend observed the client, not just signups.

Operational Guidance

Send events after durable writes in your own system.
For high-volume systems, write events to your own outbox or queue and have a worker send them to SafetyKit.
Retry transient network errors and 5xx responses with exponential backoff.
Do not retry 4xx responses without changing the request.
Store your own source event identifier in metadata if you need replay or reconciliation.