```python Python theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
# Webhook notification tutorial (Python)
# Flow: read raw body → verify HMAC-SHA-256 → parse JSON → branch on status → return 2xx
# Install: pip install flask
import hashlib
import hmac
import json
from flask import Flask, jsonify, request
app = Flask(__name__)
# ---------------------------------------------------------------------------
# Replace with your partner secret key from onboarding (server-side only)
# ---------------------------------------------------------------------------
SECRET_KEY = "
" # Example only — replace with your partner webhook secret from onboarding
@app.route("/webhooks/notification", methods=["POST"])
def handle_webhook():
# 1) Read the raw body exactly as Suki sent it (before JSON parsing).
raw_body = request.get_data(as_text=True)
timestamp = request.headers.get("generated-at", "")
message = timestamp + ":" + raw_body
# 2) Recompute HMAC-SHA-256 and compare to X-API-Key (constant-time).
expected_signature_hex = request.headers.get("X-API-Key", "")
computed_signature_hex = hmac.new(
SECRET_KEY.encode("utf-8"),
message.encode("utf-8"),
hashlib.sha256,
).hexdigest()
# Reject missing signatures before compare (empty header must not verify).
if not expected_signature_hex or not hmac.compare_digest(
computed_signature_hex, expected_signature_hex
):
return jsonify({"error": "Invalid signature"}), 401
# 3) Signature matched. Safe to parse JSON and branch on status.
try:
data = json.loads(raw_body) if raw_body else None
except json.JSONDecodeError:
return jsonify({"error": "Invalid request"}), 400
if not data or not isinstance(data, dict):
return jsonify({"error": "Invalid request"}), 400
status = data.get("status")
if status == "success":
session_id = data.get("session_id")
encounter_id = data.get("encounter_id")
sessions = data.get("sessions", [])
additional_info = data.get("additional_info")
print(f"Session {session_id} completed successfully")
print(f"Encounter ID: {encounter_id}")
print(f"Total sessions: {len(sessions)}")
if additional_info:
print(f"Additional info: {additional_info}")
# Optional follow-up links. Each href is a path; combine with your API base URL
# and call with the correct authentication for Ambient or Form filling.
links = data.get("_links") or {}
for key in (
"contents",
"encounter_content",
"structured_data",
"encounter_structured_data",
"status",
"transcripts",
):
for link in links.get(key) or []:
print(
f"{key}: {link.get('method')} {link.get('href')} - {link.get('name')}"
)
return jsonify({"message": "Notification received"}), 200
if status == "failure":
session_id = data.get("session_id")
encounter_id = data.get("encounter_id")
error_code = data.get("error_code")
error_detail = data.get("error_detail")
print(f"Session {session_id} failed")
print(f"Encounter ID: {encounter_id}")
print(f"Error Code: {error_code}")
print(f"Error Detail: {error_detail}")
return jsonify({"message": "Failure notification received"}), 200
# Timeout / cancellation (and any other verified delivery): ack so Suki does not retry.
# Example JSON for those events is not fully published yet; session_id / encounter_id are documented.
print(
f"Acknowledged status={status!r} "
f"session_id={data.get('session_id')} encounter_id={data.get('encounter_id')}"
)
return jsonify({"message": "Notification acknowledged"}), 200
if __name__ == "__main__":
# Local smoke test only. Production must use public HTTPS.
app.run(port=3000) # Example local port only — use public HTTPS in production
```
```typescript TypeScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
// Webhook notification tutorial (TypeScript / Express)
// Flow: read raw body → verify HMAC-SHA-256 → parse JSON → branch on status → return 2xx
// Install: npm install express
// Prefer Node crypto for HMAC. Keep the partner secret key on your backend only.
import crypto from 'crypto';
import express from 'express';
const app = express();
// ---------------------------------------------------------------------------
// Replace with your partner secret key from onboarding (server-side only)
// ---------------------------------------------------------------------------
const SECRET_KEY = '
'; // Example only — replace with your partner webhook secret from onboarding
// express.raw keeps the exact body bytes needed for HMAC verification.
app.post(
'/webhooks/notification',
express.raw({ type: 'application/json' }),
(req, res) => {
// 1) Read the raw body exactly as Suki sent it (before JSON parsing).
const rawBody = Buffer.isBuffer(req.body)
? req.body.toString('utf8')
: String(req.body ?? '');
const timestamp = String(req.headers['generated-at'] ?? '');
const message = `${timestamp}:${rawBody}`;
// 2) Recompute HMAC-SHA-256 and compare to X-API-Key (constant-time).
const expectedSignatureHex = String(req.headers['x-api-key'] ?? '');
const computedSignatureHex = crypto
.createHmac('sha256', SECRET_KEY)
.update(message, 'utf8')
.digest('hex');
// Reject missing signatures before compare (empty header must not verify).
const signaturesMatch =
Boolean(expectedSignatureHex) &&
computedSignatureHex.length === expectedSignatureHex.length &&
crypto.timingSafeEqual(
Buffer.from(computedSignatureHex, 'utf8'),
Buffer.from(expectedSignatureHex, 'utf8'),
);
if (!signaturesMatch) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 3) Signature matched. Safe to parse JSON and branch on status.
let data: Record | null = null;
try {
data = rawBody ? (JSON.parse(rawBody) as Record) : null;
} catch {
return res.status(400).json({ error: 'Invalid request' });
}
if (!data) {
return res.status(400).json({ error: 'Invalid request' });
}
const status = data.status;
if (status === 'success') {
const sessionId = data.session_id;
const encounterId = data.encounter_id;
const sessions = (data.sessions as unknown[]) || [];
const additionalInfo = data.additional_info;
console.log(`Session ${sessionId} completed successfully`);
console.log(`Encounter ID: ${encounterId}`);
console.log(`Total sessions: ${sessions.length}`);
if (additionalInfo) {
console.log('Additional info:', additionalInfo);
}
// Optional follow-up links. Each href is a path; combine with your API base URL
// and call with the correct authentication for Ambient or Form filling.
const links = (data._links as Record>>) || {};
for (const key of [
'contents',
'encounter_content',
'structured_data',
'encounter_structured_data',
'status',
'transcripts',
] as const) {
for (const link of links[key] || []) {
console.log(
`${key}: ${link.method} ${link.href} - ${link.name}`,
);
}
}
return res.status(200).json({ message: 'Notification received' });
}
if (status === 'failure') {
console.log(`Session ${data.session_id} failed`);
console.log(`Encounter ID: ${data.encounter_id}`);
console.log(`Error Code: ${data.error_code}`);
console.log(`Error Detail: ${data.error_detail}`);
return res.status(200).json({ message: 'Failure notification received' });
}
// Timeout / cancellation (and any other verified delivery): ack so Suki does not retry.
// Example JSON for those events is not fully published yet; session_id / encounter_id are documented.
console.log(
'Acknowledged status=',
status,
'session_id=',
data.session_id,
'encounter_id=',
data.encounter_id,
);
return res.status(200).json({ message: 'Notification acknowledged' });
},
);
// Local smoke test only. Production must use public HTTPS.
app.listen(3000, () => {
// Example local port only — use public HTTPS in production
console.log('Webhook receiver listening on http://localhost:3000');
});
```