Batch'd API Docs — ERP Webhook

POST /webhook-recall

Create a recall event and immediately notify all connected retailer stores

POST https://app.batchdapp.com/.netlify/functions/webhook-recall

When you fire this endpoint, Batch'd will:

Create a recall_event record in the database
Distribute it to all active retailer trading partners
Create per-store acknowledgement records (5-step chain: notified → acknowledged → pulled → disposed → confirmed)
Cross-reference against scan history to compute unit exposure immediately
Send recall alert emails to each retailer's contact address

Average time to all stores notified: < 90 seconds from webhook receipt.

Authentication

All requests must include your manufacturer API key as a header.

Header	Value	Required
X-Batchd-Api-Key	Your manufacturer API key from the Batch'd portal under Settings → API Key	Required
Content-Type	application/json	Required

# Example using curl
curl -X POST https://app.batchdapp.com/.netlify/functions/webhook-recall \
  -H "X-Batchd-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{...}'

Keep your API key secret. Do not include it in client-side code or commit it to source control. If compromised, regenerate it immediately in the Batch'd manufacturer portal.

Request body

Send a JSON object with the following fields:

Field	Type	Description	Required
product_name	string	Full product name as it appears on packaging. Used to match against retailer scan records.	Required
lot_number	string	Lot or batch code. Must match exactly the format printed on the product. Include all characters including prefixes (e.g. `L2026-04-01A`).	Required
reason	string	Human-readable reason for the recall. Included in notification emails and dashboard display.	Required
severity	string	Classification. Must be one of: `unknown`, `class_i`, `class_ii`, `class_iii`, `market_withdrawal`	Required
barcode	string	EAN-13 or UPC-A barcode. Improves matching accuracy when lot codes vary in format.	Optional
description	string	Extended description — allergen details, affected date range, authority reference numbers, etc.	Optional
authority_reference	string	Regulatory case number (e.g. FDA recall number, Mattilsynet case reference).	Optional
is_drill	boolean	Set to `true` to send a mock recall drill. Retailers see "[DRILL]" banners and emails are flagged. Drill records are tracked separately and excluded from compliance reporting.	Optional
target_retailer_ids	string[]	Array of specific Batch'd retailer org IDs to target. If omitted, the recall is sent to all active trading partners.	Optional

{
  "product_name": "Gilde Kjøttdeig 400g",
  "lot_number":    "L2026-04-01A",
  "reason":       "Potential Listeria monocytogenes contamination",
  "severity":     "class_i",
  "barcode":      "7038010013882",
  "description":  "Lot produced 2026-04-01. All retailers please remove from shelf immediately. Authority reference: MT-2026-00142.",
  "authority_reference": "MT-2026-00142",
  "is_drill":     false
}

Response

On success, the endpoint returns 200 OK with:

{
  "recall_event_id": "8f3a2b1c-...",  // UUID of the created recall event
  "retailer_count":  12,             // Number of retailers notified
  "store_count":     47,             // Total stores across all retailers
  "emails_sent":     12,             // Confirmation emails dispatched
  "is_drill":        false
}

200

Recall created and distributed successfully

401

Missing or invalid API key

400

Missing required fields — check product_name, lot_number, reason, severity

422

Invalid severity value

500

Internal error — retry with exponential backoff

Error handling

All errors return a JSON body with an error field:

{ "error": "product_name is required" }

We recommend implementing retry logic with exponential backoff for 5xx errors. Network timeouts should be set to at least 30 seconds — the webhook creates DB records, distributes to retailers, and sends emails synchronously.

Idempotency: The webhook does not currently support idempotency keys. If your ERP retries on timeout, a duplicate recall event may be created. Deduplication by product+lot is applied automatically in the retailer dashboard, but avoid retrying 200 responses.

SAP integration

Trigger the webhook from an SAP Business Process Automation or ABAP program on quality notification creation. Map SAP QM fields as follows:

SAP Field	Batch'd Field	Notes
QMEL-QMTXT (short text)	reason	Quality notification description
MARA-MAKTX (material desc)	product_name	Material long text preferred
MCH7-CHARG (batch number)	lot_number	Include plant prefix if applicable
MARA-EAN11 (EAN/UPC)	barcode	International Article Number
QM notification category	severity	Map to class_i / class_ii / class_iii

// Example: SAP BPA HTTP call via Groovy script
def payload = [
  product_name: materialDescription,
  lot_number:   batchNumber,
  reason:       notificationText,
  severity:     mapSeverity(notificationCategory),
  barcode:      eanNumber
]
def response = httpClient.post(
  url:     'https://app.batchdapp.com/.netlify/functions/webhook-recall',
  headers: ['X-Batchd-Api-Key': apiKey, 'Content-Type': 'application/json'],
  body:    JsonOutput.toJson(payload)
)

Oracle / Microsoft Dynamics

Oracle Cloud SCM: Use Oracle Integration Cloud (OIC) with an HTTP adapter. Trigger on Quality Issue lifecycle event type "Recall" or "Withdrawal".

Microsoft Dynamics 365: Use Power Automate with an HTTP action triggered on a Recall work order status change. Map Product Name and Lot Tracking Number to the corresponding Batch'd fields.

// Power Automate — HTTP action body (dynamic content)
{
  "product_name": "@{triggerBody()?['ProductName']}",
  "lot_number":   "@{triggerBody()?['LotNumber']}",
  "reason":       "@{triggerBody()?['RecallReason']}",
  "severity":     "class_i"
}

Contact ian.w.race@gmail.com for dedicated integration support, field mapping worksheets, or to schedule a technical call with your ERP team.

Testing

Use the "is_drill": true flag to send test recalls without affecting live operations. Drill events:

Appear to all retailers with an amber "[DRILL]" banner
Trigger the full 5-step acknowledgement chain
Send notification emails clearly labelled as drills
Generate response time metrics for compliance reporting
Are excluded from regulatory audit trail exports

We recommend running a drill before going live with your ERP integration to verify the field mapping and confirm all retail contacts receive the email correctly.

# Test recall drill — safe to run at any time
curl -X POST https://app.batchdapp.com/.netlify/functions/webhook-recall \
  -H "X-Batchd-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Integration Test Product",
    "lot_number":   "TEST-001",
    "reason":       "ERP integration test — not a real recall",
    "severity":     "unknown",
    "is_drill":     true
  }'

Expected response for a successful drill:
{"recall_event_id":"...","retailer_count":N,"store_count":N,"emails_sent":N,"is_drill":true}