AI API

AI-powered payload explanation, code generation, and failure diagnosis

AI features require a Starter plan or above. Requests made on the Free plan return a 403 Forbidden response.

The AI API lets you work with captured events in natural language — explain what a payload means, generate typed interfaces and handler code, or get a diagnosis when a delivery fails.

All AI endpoints operate on a specific event. You need the endpoint ID and event ID from the Events API.

---

Explain an event

GET /api/endpoints/:id/events/:eventId/ai/explain

Returns a plain English explanation of what the webhook event means. Useful for quickly understanding an unfamiliar payload without reading the raw JSON.

id · string · required

The endpoint ID.

eventId · string · required

The event ID.

cURL

curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/explain \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

explanation · string

A plain English description of what this webhook event represents.

{
  "explanation": "A customer just completed a payment of ₦15,000 for order #1234. The payment was processed successfully via card ending in 4242."
}

---

Generate a TypeScript interface

GET /api/endpoints/:id/events/:eventId/ai/schema

Analyzes the event payload and generates a TypeScript interface that matches its structure. Use this to get type safety in your webhook handler without writing the interface by hand.

id · string · required

The endpoint ID.

eventId · string · required

The event ID.

cURL

curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/schema \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

schema · string

A TypeScript interface definition derived from the event payload.

{
  "schema": "interface StripePaymentIntentSucceeded {\n  id: string;\n  type: 'payment_intent.succeeded';\n  data: {\n    object: {\n      id: string;\n      amount: number;\n      currency: string;\n      status: 'succeeded';\n    };\n  };\n}"
}

---

Generate handler code

POST /api/endpoints/:id/events/:eventId/ai/handler

Generates a ready-to-use webhook handler function for the event in your chosen language and framework.

id · string · required

The endpoint ID.

eventId · string · required

The event ID.

language · string · required

The programming language for the generated handler. Supported values: typescript, javascript, python, go.

framework · string · required

The web framework to target. Supported values: express, fastify, nextjs, fastapi, gin.

cURL

curl -X POST https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/handler \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "typescript",
    "framework": "express"
  }'

The table below shows which language and framework combinations are supported:

Language	Frameworks
typescript	express, fastify, nextjs
javascript	express, fastify, nextjs
python	fastapi
go	gin

Response

code · string

The generated handler function as a string, ready to paste into your project.

{
  "code": "import { Request, Response } from 'express';\n\nexport async function handleStripeWebhook(req: Request, res: Response) {\n  const event = req.body;\n\n  if (event.type === 'payment_intent.succeeded') {\n    const paymentIntent = event.data.object;\n    // TODO: fulfill the order for paymentIntent.id\n    console.log('Payment succeeded:', paymentIntent.id);\n  }\n\n  res.json({ received: true });\n}"
}

---

Diagnose a failed delivery

GET /api/endpoints/:id/events/:eventId/ai/diagnose

Returns an AI-generated diagnosis of why an event failed to deliver and what you can do to fix it. Use this when an event has a failed or dead_letter status.

id · string · required

The endpoint ID.

eventId · string · required

The event ID. The event should have a failed or dead_letter status for meaningful results.

cURL

curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/diagnose \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

diagnosis · string

A description of the likely cause of the delivery failure.

suggestion · string

Recommended steps to resolve the issue.

{
  "diagnosis": "Your destination returned a 500 Internal Server Error on all 5 delivery attempts. The response body contained 'Cannot read properties of undefined (reading \"id\")', which suggests an unhandled exception in your webhook handler.",
  "suggestion": "Check that your handler guards against missing fields before accessing nested properties. Add a try/catch block around your handler logic and make sure your server returns a 2xx status code to acknowledge receipt, even if you process the event asynchronously."
}