> ## Documentation Index
> Fetch the complete documentation index at: https://bobprince-78964c2b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI API

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

<Note>
  AI features require a **Starter plan or above**. Requests made on the Free plan return a `403 Forbidden` response.
</Note>

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](/api-reference/events).

***

## 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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/explain \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

<ResponseField name="explanation" type="string">
  A plain English description of what this webhook event represents.
</ResponseField>

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/schema \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

<ResponseField name="schema" type="string">
  A TypeScript interface definition derived from the event payload.
</ResponseField>

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID.
</ParamField>

<ParamField body="language" type="string" required>
  The programming language for the generated handler. Supported values: `typescript`, `javascript`, `python`, `go`.
</ParamField>

<ParamField body="framework" type="string" required>
  The web framework to target. Supported values: `express`, `fastify`, `nextjs`, `fastapi`, `gin`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

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**

<ResponseField name="code" type="string">
  The generated handler function as a string, ready to paste into your project.
</ResponseField>

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID. The event should have a `failed` or `dead_letter` status for meaningful results.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/ai/diagnose \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

<ResponseField name="diagnosis" type="string">
  A description of the likely cause of the delivery failure.
</ResponseField>

<ResponseField name="suggestion" type="string">
  Recommended steps to resolve the issue.
</ResponseField>

```json theme={null}
{
  "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."
}
```