# Intégrer Datoka Hooks / Integrate Datoka Hooks

Bêta gratuite : 100 nouveaux événements/jour UTC, 20 livraisons en attente, 64 Kio par événement.
Free allowance: 100 new events/day UTC, 20 pending deliveries, 64 KiB per event. Optional prepaid credits beyond the daily allowance; see /pricing.

## 1. Préparer le destinataire / Prepare the receiver
Créez votre accès sur la page d'accueil, téléchargez le fichier privé, publiez le challenge sur votre domaine HTTPS puis validez le destinataire. Le guide /getting-started décrit les signatures HMAC et la déduplication côté réception.
Create an access on the home page, save the private credentials, publish the ownership challenge on your HTTPS origin and verify it. Receiver HMAC and deduplication are described at /getting-started.

Exemples téléchargeables / Download examples: https://datoka-hooks-test.bhazarstudio.workers.dev/examples
Python 3.10+ sans dépendance / no dependencies: python send-http.py ACCESS_FILE STABLE_EVENT_ID PAYLOAD_FILE

## 2. Développeurs : HTTP / Developers: HTTP
POST https://datoka-hooks-test.bhazarstudio.workers.dev/v1/hooks/HOOK_ID/events
Authorization: Bearer DELIVERY_TOKEN
Content-Type: application/json
X-Datoka-Event-Id: job-demo-001

{"type":"job.completed","jobId":"demo-001"}

Utilisez un identifiant stable par événement métier. HTTP 202 confirme l'acceptation, pas la livraison. En cas de perte de réponse, réutilisez exactement l'identifiant, le type de contenu et les octets d'origine.
Use one stable ID per business event. HTTP 202 confirms acceptance, not delivery. If the response is lost, retry with the same ID, content type and exact bytes.

GET https://datoka-hooks-test.bhazarstudio.workers.dev/v1/hooks/HOOK_ID/deliveries/DELIVERY_ID
Authorization: Bearer DELIVERY_TOKEN

Attendez quelques secondes entre les lectures ; arrêtez quand state vaut delivered ou failed. Les états accepting, queued, sending et recording sont transitoires. Une réponse 2xx du destinataire est une observation, pas une garantie de traitement métier.
Poll a few seconds apart and stop on delivered or failed. A receiver 2xx is an observation, not proof of completed business processing.

## 3. Agents : MCP / Agents: MCP
Découverte et inscription : https://datoka-hooks-test.bhazarstudio.workers.dev/mcp
Après vérification, préférez l'endpoint limité à votre hook :
https://datoka-hooks-test.bhazarstudio.workers.dev/v1/hooks/HOOK_ID/mcp
Configurez Authorization: Bearer DELIVERY_TOKEN dans le gestionnaire de secrets du client, pas dans un prompt public.
After verification, configure the hook-specific endpoint with its bearer token in your client's secret store.

Outil / tool: accept_hook_event
Arguments: eventId (stable), contentType (application/json), bodyBase64 (octets exacts encodés en base64 standard / exact bytes in standard base64).
Puis / then: get_hook_delivery avec / with deliveryId.
Vérification / verification: verify_hook_receipt avec les champs event et receipt retournés.

Exemples Node 24 dans l'archive source (après npm ci) :
node examples/send-http.mjs /chemin/prive/datoka-hooks-access.json job-demo-001 examples/event.json
node examples/send-mcp.mjs /chemin/prive/datoka-hooks-access.json job-demo-001 examples/event.json
Ces deux commandes envoient le même événement : exécuter les deux avec le même fichier produit une seule admission.
Both examples submit the same event: running both with an unchanged file and ID yields one admission.

## 4. Automatisation : module de requête HTTP / Automation: HTTP request step
Compatible avec tout outil capable d'envoyer des en-têtes et un corps brut (par exemple n8n ou Make).
1. Stocker DELIVERY_TOKEN comme secret de connexion.
2. Configurer POST et les trois en-têtes de l'exemple HTTP.
3. Utiliser l'identifiant de l'événement source comme X-Datoka-Event-Id ; ne pas utiliser l'heure d'exécution d'une reprise.
4. Sérialiser le JSON une seule fois et conserver ses octets pour les reprises.
5. Sauvegarder deliveryId de la réponse, puis lire son état avec GET.
6. Acheminer failed vers votre traitement d'erreur. Pour 409, corriger le conflit au lieu de changer silencieusement l'identifiant.
Store the token as a credential, preserve the source event ID and serialized body across retries, save deliveryId and poll its status. Handle failed explicitly; never hide an idempotency conflict by changing its ID.

Il s'agit d'une recette HTTP ; aucun connecteur natif n8n/Make n'est annoncé. L'accès nécessite le contrôle du domaine de réception et son challenge, y compris avec un outil d'automatisation.
This is an HTTP recipe, not a native n8n/Make connector. You must control the receiving origin and serve its ownership challenge.

## Dépannage / Troubleshooting
401: vérifier le token actif et le statut de vérification/révocation / check token and access status.
409: même identifiant mais contenu différent / same ID with different content.
413: réduire le corps à 65536 octets / reduce body to 65536 bytes.
429: quota atteint ; patienter, conserver l'identifiant / quota reached; wait and preserve ID.
503 ou perte réseau : admission incertaine ; reprise idempotente / uncertain acceptance; retry idempotently.
Conservez les credentials hors des dépôts, captures et journaux publics. Ne transmettez jamais managementToken au destinataire.
Keep credentials out of repositories and public logs. Never send managementToken to the receiver.

OPTIONAL EXTRA CREDITS / CREDITS SUPPLEMENTAIRES
GET /pricing gives the active offer. GET /v1/public/hooks/{hookId}/credits with managementToken reads the balance. POST there with {"purchaseId":"stable-id"} requests an x402 v2 quote; a quote does not charge money. After explicitly signing the offer, retry the same body with PAYMENT-SIGNATURE (base64 payment JSON). On uncertainty reuse the same purchaseId and signed payment. MCP tools: get_hook_credits, purchase_hook_credits. Daily free allowance stays available. Credits cover extra admissions, not guaranteed delivery.

## Trois usages / Three use cases
1. Fin de tâche / Job completion: envoyer {"type":"job.completed","jobId":"job-001","status":"complete"} avec eventId job-001-completed. Le destinataire peut déclencher la suite du workflow. / The receiver can continue the workflow.
2. Résultat d'agent / Agent result: envoyer {"type":"agent.result.ready","taskId":"task-001","resultId":"result-001"} avec eventId task-001-result-001. Transmettre une référence privée résoluble par le destinataire, jamais un token d'accès dans un lien public. / Send an authorized result reference; keep access tokens private.
3. Destinataire indisponible / Receiver outage: envoyer une seule fois un événement à identifiant stable. Hooks conserve la livraison et reprend les erreurs temporaires jusqu'aux limites configurées. Lire get_hook_delivery ; traiter failed explicitement. / Submit once with a stable ID, poll status and handle terminal failure.
Les reprises Hooks ne dépensent pas de nouveaux crédits. HTTP 202 n'est pas une livraison ; HTTP 2xx du destinataire n'est pas une preuve du traitement métier.
Retries do not spend additional credits. Acceptance and receiver HTTP responses are relay observations only.

## Décider d'acheter / Purchase decision
Utiliser d'abord les 100 admissions gratuites par jour UTC. Consulter /pricing et le solde. Le pack actuel coûte 0,10 USDC pour 100 admissions supplémentaires (0,001 USDC chacune si tout est utilisé), sans abonnement ni recharge automatique. Un besoin d'une seule admission nécessite quand même le pack entier.
Use the daily free allowance first. Read /pricing and your balance. The current pack costs 0.10 USDC for 100 extra admissions, prepaid, with no subscription or automatic renewal. One extra event still requires the entire pack.
Acheter uniquement avec un budget autorisé et un portefeuille compatible EOA / EIP-3009 sur Base. Tous les portefeuilles d'agents ne sont pas compatibles. Un devis ne débite rien ; ne jamais multiplier les purchaseId pour résoudre une réponse incertaine.
Buy only within an authorized budget using a compatible EOA / EIP-3009 wallet on Base. Not every agent wallet is supported. A quote charges nothing; never create new purchase IDs to resolve uncertain responses.