> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailgun Webhook Setup Guide

> Configure Mailgun to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/mailgun#getting-started) on the Mailgun connector page.

<section data-guide-section data-guide-scopes="">
  <h2>How Mailgun webhooks are set up</h2>

  <p>StackOne creates and manages the webhook subscription automatically when the account is connected - there is nothing to configure in Mailgun and no URL to paste. StackOne registers one account-level Mailgun webhook per event you enable, and removes them when the account is disconnected.</p>

  <ul>
    <li>Webhooks are account-level, so they fire for every sending domain on the Mailgun account.</li>
    <li>Only the events you enable in StackOne are registered in Mailgun and delivered.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Mailgun message events can be enabled.</p>

  <Steps>
    <Step title="Message pipeline events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events fired as Mailgun processes an outgoing message.</p>

        <ul>
          <li><strong>Accepted</strong> (`accepted`) — Fired when Mailgun accepts a message for sending and queues it</li>
          <li><strong>Delivered</strong> (`delivered`) — Fired when the recipient's mail server accepts the message</li>
          <li><strong>Permanent Failure</strong> (`permanent_fail`) — Fired when a message permanently fails to deliver (hard bounce, suppressed recipient, or retries exhausted)</li>
          <li><strong>Temporary Failure</strong> (`temporary_fail`) — Fired when the recipient's mail server temporarily defers the message (soft bounce); Mailgun keeps retrying</li>
        </ul>
      </div>
    </Step>

    <Step title="Engagement events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events fired by recipient interactions with a delivered message.</p>

        <ul>
          <li><strong>Opened</strong> (`opened`) — Fired when a recipient opens the message. Requires open tracking on the sending domain</li>
          <li><strong>Clicked</strong> (`clicked`) — Fired when a recipient clicks a tracked link. Requires click tracking on the sending domain</li>
          <li><strong>Unsubscribed</strong> (`unsubscribed`) — Fired when a recipient unsubscribes through the Mailgun unsubscribe link</li>
          <li><strong>Spam Complaint</strong> (`complained`) — Fired when a recipient marks the message as spam</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Each request carries one event under `event-data`, with a `signature` block (timestamp, token, and an HMAC-SHA256 signature made with the account's Webhook Signing Key). Both failure events arrive with event `failed`, and `severity` tells them apart. Test deliveries from Mailgun's <strong>Send test webhook</strong> button are flagged `is-test-mode` and are acknowledged without being delivered as events.</p>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.