Agent Webhooks

Agent webhooks are designed to allow you to launch an agent in response to a message from a platform like email, slack, etc.

Not to be confused with webhooks, which allows you to receive a notification when an approval or human contact is completed, Agent webhooks are specifically designed for kicking off new tasks and workflows

​

Use cases

Agent webhooks are useful for:

• Forwarding an email to an agent to handle
• Launching an agent workflow in response to a message in Slack

You can see examples of using agent webhooks in:

• Mailcrew - an open source agent that uses HumanLayer to receive and respond to inbound emails
• FastAPI Email Example - a complete example of handling inbound emails with FastAPI

​

Overview

To get started with agent webhooks, you’ll need to:

1. Implement an AI Agent in your language and/or framework of choice, and create an API endpoint that can launch the agent
2. Create a publicly reachable URL that can receive webhooks from HumanLayer (we recommend ngrok to catch webhooks while you’re developing locally)
3. Create a new agent webhook in the HumanLayer dashboard, setting the callback URL to your webhook endpoint

4. Test the webhook in the HumanLayer dashboard
5. Test the webhook by sending an email to the webhook email address (slack support coming soon)

​

Email Payload

For email webhooks, the payload will be look like

a JSON example might look like

{
  "from_address": "overworked-admin@coolcompany.com",
  "to_address": "cool-agent@humanlayer.dev",
  "subject": "FWD: help",
  "body": "can you add a ticket for this?",
  "message_id": "<1234567890@mailsrv.coolcompany.com>",
  "raw_email": "This is a placeholder for a test email - if this were a real email, it would include headers, etc.",
  "datetime": "2024-01-02T00:00:00Z",
  "previous_thread": [
    {
      "from_address": "needy-employee@coolcompany.com",
      "to_address": ["overworked-admin@coolcompany.com"],
      "cc_address": [],
      "subject": "help",
      "content": "i need some help",
      "raw_email": "i need some help",
      "datetime": "2024-01-01T00:00:00Z"
    }
  ]
}

​

Using Ngrok for local development

1. Start your local API server and note the port it’s running on
2. Install ngrok and run ngrok http <port>
3. Copy the ngrok URL and use it as the callback URL in the HumanLayer dashboard