Webhook Payloads

Complete reference for webhook payloads sent by inbox.dog agents.

Webhook Overview

When an agent executes the webhook tool, it sends a POST request to your configured URL with email and action data.

Basic Webhook Call

webhook({
  url: "https://your-endpoint.com/webhook",
  method: "POST",
  headers: {
    "Authorization": "Bearer your-token"
  },
  data: {
    email: emailData,
    agent: agentConfig,
    actions: executedActions
  }
})

Payload Structure

Complete Payload Example

{
  "email": {
    "id": "18c5f8a3b4d2e1f0",
    "threadId": "18c5f8a3b4d2e1f0",
    "messageId": "<message-id@mail.gmail.com>",
    "from": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "to": [
      {
        "email": "support@company.com",
        "name": "Support Team"
      }
    ],
    "cc": [],
    "bcc": [],
    "subject": "Support request: Password reset",
    "body": "Hi, I need to reset my password for account jane@example.com",
    "htmlBody": "<p>Hi, I need to reset my password...</p>",
    "date": "2024-01-15T10:30:00Z",
    "snippet": "Hi, I need to reset my password...",
    "labels": ["INBOX", "UNREAD"],
    "hasAttachment": false,
    "attachments": []
  },
  "agent": {
    "id": "agent_abc123",
    "name": "Support Triage",
    "description": "Automatically triages support emails"
  },
  "actions": [
    {
      "tool": "searchDocuments",
      "input": {
        "query": "password reset process"
      },
      "result": {
        "success": true,
        "documents": ["password-reset-policy.pdf"]
      },
      "timestamp": "2024-01-15T10:31:00Z"
    },
    {
      "tool": "reply",
      "input": {
        "to": "customer@example.com",
        "subject": "Re: Support request: Password reset",
        "body": "Here's how to reset your password..."
      },
      "result": {
        "success": true,
        "messageId": "new-message-id@mail.gmail.com"
      },
      "timestamp": "2024-01-15T10:31:05Z"
    },
    {
      "tool": "label",
      "input": {
        "labelIds": ["support-resolved"]
      },
      "result": {
        "success": true,
        "labelsApplied": ["support-resolved"]
      },
      "timestamp": "2024-01-15T10:31:10Z"
    }
  ],
  "metadata": {
    "organizationId": "org_xyz",
    "userId": "user_123",
    "processingTime": 10.5,
    "timestamp": "2024-01-15T10:31:15Z"
  }
}

Payload Fields

Email Object

Agent Object

Actions Array

Each action represents a tool execution:

Metadata Object

Common Webhook Patterns

Zapier Integration

Zapier Webhook Trigger:

{
  "email": {
    "from": "{{email.from.email}}",
    "subject": "{{email.subject}}",
    "body": "{{email.body}}"
  },
  "agent": "{{agent.name}}",
  "actions": "{{actions}}"
}

Make Integration

Make Webhook Module:

1. Add "Webhooks" → "Custom webhook"
2. Copy webhook URL
3. Configure in agent action
4. Process data in Make scenario

Custom API Endpoint

Express.js Example:

app.post('/webhook', (req, res) => {
  const { email, agent, actions } = req.body;
  
  // Process email data
  console.log(`Agent ${agent.name} processed email from ${email.from.email}`);
  
  // Trigger your workflow
  createTicket(email);
  
  res.json({ success: true });
});

Python Flask Example:

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    email = data['email']
    agent = data['agent']
    actions = data['actions']
    
    # Process email
    process_email(email, agent, actions)
    
    return jsonify({'success': True})

Webhook Security

Authentication

Add authentication headers in webhook configuration:

webhook({
  url: "https://your-api.com/webhook",
  headers: {
    "Authorization": "Bearer your-secret-token",
    "X-Webhook-Signature": "signature-here"
  }
})

Verification

Verify webhook authenticity:

1. Check Authorization header
2. Validate payload signature (if implemented)
3. Verify source IP (optional)

Error Handling

Retry Logic

Webhooks automatically retry on failure:

• First retry: 5 seconds
• Second retry: 30 seconds
• Third retry: 5 minutes

Error Response

Your endpoint should return:

{
  "success": true,
  "message": "Webhook processed"
}

Or for errors:

{
  "success": false,
  "error": "Error message"
}

Use Case Examples

Create Support Ticket

// Webhook receives email
// Create ticket in your system
const ticket = await createTicket({
  subject: email.subject,
  body: email.body,
  from: email.from.email,
  agent: agent.name
});

// Update ticket with agent actions
if (actions.some(a => a.tool === 'reply')) {
  await updateTicket(ticket.id, { status: 'replied' });
}

Send Slack Notification

// Webhook → Slack
await slack.postMessage({
  channel: '#support',
  text: `Agent ${agent.name} processed email from ${email.from.email}`,
  attachments: [{
    title: email.subject,
    text: email.snippet
  }]
});

Update CRM

// Webhook → CRM
const contact = await crm.findContact(email.from.email);
if (contact) {
  await crm.addActivity(contact.id, {
    type: 'email',
    subject: email.subject,
    body: email.body,
    agent: agent.name
  });
}

Testing Webhooks

Using ngrok (Local Testing)

1. Start local server: python -m http.server 8000
2. Start ngrok: ngrok http 8000
3. Use ngrok URL in webhook config
4. Test with agent

Webhook Testing Tools

• webhook.site - Temporary webhook URLs
• RequestBin - Inspect webhook payloads
• Postman - Test webhook endpoints

Next Steps

• See API overview →
• Learn about MCP server →
• Explore agent configuration →