# validate_custom_events

Validate event payload schema and app ownership without storing, observing or triggering anything.

## Purpose

Validate the exact `/api/events` JSON body without storing an event, updating observations, triggering a Flow or sending a message. This uses the ingestion schema and checks workspace ownership for every supplied app ID.

## Credentials and scope

Owner workspace credential. App-bound affiliate credentials cannot access this tool.

## Inputs

- `payload`: the single event object or an object containing an `events` array of 1–50 events.

## Example request

The identifiers and merchant are fictional. This dry run does not assert that the app exists in your workspace.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_custom_events",
    "arguments": {
      "payload": {
        "appId": "11111111-1111-4111-8111-111111111111",
        "shopDomain": "example.myshopify.com",
        "name": "urgency_configuration_saved",
        "eventId": "opaque-lifecycle-save-id",
        "occurredAt": "2026-10-07T10:00:00Z",
        "properties": {}
      }
    }
  }
}
```

POST this JSON to `https://heycrust.com/api/mcp` with `Content-Type: application/json` and `Authorization: Bearer <YOUR_CREDENTIAL>`. Inspect JSON-RPC errors and `result.isError`, then parse the JSON text inside `result.content`.

## Result

`ok: true` means the validation operation ran, and `dryRun: true` distinguishes it from ingestion. Check `valid`: invalid input returns issue codes, paths and messages or an app ownership error. Valid input returns count, check time and normalized event summaries with app scope, occurrence time, whether an ID was supplied and whether a future timestamp would be clamped. It omits property values and external event IDs.

## Effects and verification

This is a read-only check. It does not reserve an ID, check existing duplicates/conflicts, validate milestone evidence or prove delivery. No payload is persisted. The submitted payload still travels through your MCP client and its logging infrastructure: use minimal allowlisted properties and never submit secrets. Read the [backend event contract](/docs/developers/backend-events) and [lifecycle recipes](/docs/developers/custom-event-lifecycle) before implementing delivery.

## Troubleshooting

A `valid: false` result can accompany JSON-RPC success. Correct the payload or app ownership; do not test it by posting a synthetic live event. A successful dry run is insufficient to declare an integration verified end to end.