# Incoming Webhook Triggers

Use incoming webhooks to trigger automations

Incoming webhooks allow external systems to trigger Mailnaptic automations by sending an HTTP request to a Mailnaptic-generated URL. This is useful when you want events from your own application, payment processor, or any third-party service to start an automated workflow.

## How incoming webhooks work

When you create an incoming webhook trigger for an automation, Mailnaptic generates a unique URL. Any system that sends an HTTP POST to that URL with a valid JSON payload can trigger the automation for a specific contact.

## Creating an automation with a webhook trigger

1. Go to **Automations** and create a new automation.
2. For the trigger type, select **Incoming Webhook**.
3. Mailnaptic generates a unique webhook URL. Copy this URL — you will configure it in the external system that will trigger the automation.
4. Build your automation flow (delays, emails, conditions, etc.).
5. Activate the automation.

## Payload requirements

The incoming webhook expects a JSON POST body. At minimum, you must include a way to identify the contact:

```
{
  "email": "jane@example.com",
  "data": {
    "plan": "pro",
    "amount": 49.99
  }
}
```

The `email` field is required and must match an existing contact in your Mailnaptic account. The `data` object is optional and can contain any key-value pairs you want to make available to the automation flow.

## Using payload data in emails

Any properties sent in the `data` object are available as merge tags within the automation's email steps. For example, if your payload includes `"plan": "pro"`, you can reference it in your email template:

```
Thanks for upgrading to the {{trigger.plan}} plan!
```

## Authentication

Each incoming webhook URL contains a unique, cryptographically random token that acts as authentication. Anyone with the URL can trigger the automation, so treat it like a secret:

- Do not expose the URL in client-side code or public repositories.
- Store it in environment variables or a secrets manager on your server.
- If compromised, delete the automation trigger and create a new one to generate a fresh URL.

## Rate limits

Incoming webhooks are rate-limited to **60 requests per minute** per automation. Requests exceeding this limit receive a `429 Too Many Requests` response. If you need to enroll contacts in bulk, use the API's batch endpoints instead.

## Common use cases

- **Payment received:** Your payment processor (Stripe, PayPal) sends a webhook to Mailnaptic when a payment succeeds, triggering a thank-you email sequence.
- **Form submission:** A form tool (Typeform, JotForm) posts data to Mailnaptic, starting an onboarding automation.
- **CRM stage change:** When a deal moves to "Closed Won" in your CRM, trigger a welcome sequence.
- **App events:** Your own application fires a webhook when a user completes setup, triggering an adoption email series.

## Error handling

| Response code | Meaning |
| --- | --- |
| `200` | Contact found and enrolled in automation |
| `400` | Invalid JSON or missing `email` field |
| `404` | Contact not found in your Mailnaptic account |
| `429` | Rate limit exceeded |

> **Tip:** Combine incoming webhooks with conditional steps in your automation to branch based on the payload data — for example, send different emails based on the `plan` value.
