marv.Inbox Developer API

What you can build

Base URL and access

The API is live in production today. You do not need an upgrade or a separate developer account.

Base URL

https://api.marvinbox.com

Getting credentials

Sign in to app.marvinbox.com and open Settings, Developer. Create an integration client to get a client id and client secret for the API, and register a webhook endpoint to receive events. A workspace admin role is required to manage both.

Quickstart

Three steps from zero to your first authenticated call.

1. 1

   Create an integration client

   In Settings, Developer, Integration clients, create a client and pick the scopes it needs. Copy the client id and client secret. The secret is shown only once.

2. 2

   Exchange credentials for a token

   Call the token endpoint with your client id and secret. You get back a short lived bearer token, valid for one hour.

3. 3

   Call the API

   Send the token as an Authorization header on every request. The token already identifies your workspace, so there is no tenant header to set.

curl -X POST https://api.marvinbox.com/external/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "marv_ic_live_...",
    "client_secret": "marv_cs_..."
  }'

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "customers:write messages:write"
}

curl -X POST https://api.marvinbox.com/external/v1/customers/upsert \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-key>" \
  -d '{
    "phone": "+972501234567",
    "name": "Jane Doe",
    "externalCustomerId": "crm-001"
  }'

Authentication

Scopes

Grant a client only the scopes it needs. Each endpoint below lists its required scope.

REST endpoints

All endpoints are under the base URL above. Writes accept an Idempotency-Key header.

Webhooks

Webhooks push events to your server the moment they happen, so you do not have to poll.

Register an endpoint

In Settings, Developer, Webhooks, add your receiver URL and choose the events you want. Copy the signing secret shown on creation. You can register up to ten endpoints, enable or disable each one, and review recent delivery attempts in the same screen.

How deliveries arrive

Each event is a POST with a JSON body and these headers:

POST /your-receiver HTTP/1.1
Content-Type: application/json
X-Marv-Event: message.created
X-Marv-Delivery: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Marv-Timestamp: 2026-06-15T10:23:45.123Z
X-Marv-Signature: v1=3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d...

A 2xx response marks the delivery successful. marv.Inbox waits up to 10 seconds for your response and retries once after 5 seconds on failure. Receiver URLs must be public; private and loopback addresses are rejected.

Event types

Subscribe to any combination of these events.

Verifying a delivery

Every delivery is signed so you can trust it came from marv.Inbox. The signature is computed over the raw request body:

v1=HMAC-SHA256(secret, "{X-Marv-Timestamp}.{X-Marv-Delivery}.{rawBody}")

Recompute it against the exact bytes you received, before JSON parsing, reject anything where the timestamp is more than five minutes old, dedupe by X-Marv-Delivery, and compare in constant time.

import { createHmac, timingSafeEqual } from 'crypto';

// marv.Inbox signs every delivery:
//   v1=HMAC-SHA256(secret, `${timestamp}.${deliveryId}.${rawBody}`)
// Verify against the EXACT raw request body, before JSON parsing.
export function verifyMarvWebhook(headers, rawBody, secret) {
  const signature  = headers['x-marv-signature'];  // "v1=<hex>"
  const timestamp  = headers['x-marv-timestamp'];   // ISO 8601
  const deliveryId = headers['x-marv-delivery'];    // UUID, dedupe on this

  // Reject anything older than 5 minutes (replay protection).
  if (Math.abs(Date.now() - Date.parse(timestamp)) > 300_000) return false;

  const expected = 'v1=' + createHmac('sha256', secret)
    .update(`${timestamp}.${deliveryId}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(signature ?? '', 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && timingSafeEqual(a, b);
}

Errors

Errors use standard HTTP status codes with a JSON body describing the problem.

Frequently asked questions