PHPackages                             chimpmatic/mailchimp-webhook-handler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. chimpmatic/mailchimp-webhook-handler

ActiveLibrary[API Development](/categories/api)

chimpmatic/mailchimp-webhook-handler
====================================

Parse and handle Mailchimp webhook payloads. Typed events, signature verification, zero dependencies, PHP 8.5+.

v1.0.0(1mo ago)00MITPHPPHP >=8.5

Since Mar 17Pushed 1mo agoCompare

[ Source](https://github.com/chimpmatic/mailchimp-webhook-handler)[ Packagist](https://packagist.org/packages/chimpmatic/mailchimp-webhook-handler)[ Docs](https://chimpmatic.com)[ RSS](/packages/chimpmatic-mailchimp-webhook-handler/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Mailchimp Webhook Handler
=========================

[](#mailchimp-webhook-handler)

[![Latest Version](https://camo.githubusercontent.com/3f98951e54477e3e6de5288effdffd73714de2e9d206f18dfbde3d85e6022a29/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368696d706d617469632f6d61696c6368696d702d776562686f6f6b2d68616e646c65722e737667)](https://packagist.org/packages/chimpmatic/mailchimp-webhook-handler)[![PHP Version](https://camo.githubusercontent.com/3254e73f07f0fdc5009afbbffe57b4e52e7d72656d001c4c6885a25feb8e0c09/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6368696d706d617469632f6d61696c6368696d702d776562686f6f6b2d68616e646c65722e737667)](https://packagist.org/packages/chimpmatic/mailchimp-webhook-handler)[![License](https://camo.githubusercontent.com/8b42a5f49cbfd58a4934f81a3cdd659d96f4d6bdd9fc882a306210fd63241b54/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6368696d706d617469632f6d61696c6368696d702d776562686f6f6b2d68616e646c65722e737667)](https://github.com/chimpmatic/mailchimp-webhook-handler/blob/main/LICENSE)

Parse and handle Mailchimp webhook payloads. Typed events, secret verification, event listeners, zero dependencies, PHP 8.5+.

**Author:** [Chimpmatic](https://chimpmatic.com)

Why This Exists
---------------

[](#why-this-exists)

Mailchimp sends webhook notifications when subscribers join, leave, update their profile, change their email, or get cleaned from your audience. Parsing these payloads means dealing with nested form data, extracting merge fields, and routing events to the right handler.

This library turns raw `$_POST` data into typed, readonly objects with a clean event listener API.

Built for [Contact Form 7 to Mailchimp](https://chimpmatic.com/connect-contact-form-7-with-mailchimp) integrations, but works with any PHP application.

Requirements
------------

[](#requirements)

- **PHP 8.5 or higher** (uses `readonly` classes and enums)
- No extensions required (zero dependencies)

A fatal error (`E_USER_ERROR`) is triggered if loaded on PHP < 8.5. The library will not run on older versions.

Installation
------------

[](#installation)

```
composer require chimpmatic/mailchimp-webhook-handler
```

Quick Start
-----------

[](#quick-start)

```
use Chimpmatic\WebhookHandler\WebhookHandler;
use Chimpmatic\WebhookHandler\WebhookEvent;
use Chimpmatic\WebhookHandler\WebhookPayload;

$handler = new WebhookHandler();

// Register listeners
$handler->on(WebhookEvent::Subscribe, function (WebhookPayload $payload): void {
    echo "New subscriber: {$payload->email}";
    echo "Name: {$payload->getMergeField('FNAME')} {$payload->getMergeField('LNAME')}";
});

$handler->on(WebhookEvent::Unsubscribe, function (WebhookPayload $payload): void {
    echo "Unsubscribed: {$payload->email} — reason: {$payload->getReason()}";
});

// Handle the incoming webhook
$payload = $handler->handle($_POST);
echo $payload->getSummary();
```

Supported Events
----------------

[](#supported-events)

EventMailchimp TypeDescription`Subscribe``subscribe`New subscriber added`Unsubscribe``unsubscribe`Subscriber removed`ProfileUpdate``profile`Subscriber updated their profile`EmailChanged``upemail`Subscriber changed their email`Cleaned``cleaned`Email bounced (hard/soft)`Campaign``campaign`Campaign sent to listWebhook Endpoint
----------------

[](#webhook-endpoint)

```
use Chimpmatic\WebhookHandler\WebhookHandler;
use Chimpmatic\WebhookHandler\WebhookException;

$handler = new WebhookHandler('your-webhook-secret');

// Mailchimp sends a GET request to validate the URL
if ($handler->isValidationRequest($_SERVER['REQUEST_METHOD'])) {
    http_response_code(200);
    exit;
}

// Verify the secret (Mailchimp appends ?secret=... to the URL)
if (!$handler->verifySecret($_GET['secret'] ?? '')) {
    http_response_code(403);
    exit;
}

try {
    $payload = $handler->handle($_POST);
    http_response_code(200);
} catch (WebhookException $e) {
    http_response_code(400);
    echo $e->getMessage();
}
```

Working with Payloads
---------------------

[](#working-with-payloads)

```
$handler->on(WebhookEvent::Subscribe, function (WebhookPayload $payload): void {
    // Basic info
    echo $payload->email;       // "john@example.com"
    echo $payload->audienceId;  // "abc123def4"
    echo $payload->firedAt;     // "2026-03-16 21:00:00"
    echo $payload->event->value; // "subscribe"

    // Merge fields
    echo $payload->getMergeField('FNAME'); // "John"
    echo $payload->getMergeField('LNAME'); // "Doe"

    // Full summary
    echo $payload->getSummary();
    // "[2026-03-16 21:00:00] subscribe — john@example.com (audience: abc123def4)"
});
```

Email Changed Events
--------------------

[](#email-changed-events)

```
$handler->on(WebhookEvent::EmailChanged, function (WebhookPayload $payload): void {
    echo "Old: {$payload->getOldEmail()}"; // "old@example.com"
    echo "New: {$payload->getNewEmail()}"; // "new@example.com"
});
```

Listen to All Events
--------------------

[](#listen-to-all-events)

```
$handler->onAny(function (WebhookPayload $payload): void {
    // Log every webhook
    error_log($payload->getSummary());
});
```

Parse Without Dispatching
-------------------------

[](#parse-without-dispatching)

```
// Just parse, don't trigger listeners
$payload = $handler->parse($_POST);

if ($payload->isSubscribe()) {
    // ...
}
```

Error Handling
--------------

[](#error-handling)

```
use Chimpmatic\WebhookHandler\WebhookException;

try {
    $handler->parse($_POST);
} catch (WebhookException $e) {
    // Empty payload, missing type, unknown event type, invalid data
}
```

Related Packages
----------------

[](#related-packages)

- [mailchimp-api-key-validator](https://packagist.org/packages/chimpmatic/mailchimp-api-key-validator) — Validate API key format and connectivity
- [mailchimp-audience-finder](https://packagist.org/packages/chimpmatic/mailchimp-audience-finder) — Find Audience IDs and merge fields
- [mailchimp-subscriber](https://packagist.org/packages/chimpmatic/mailchimp-subscriber) — Subscribe contacts with merge fields

Links
-----

[](#links)

- [Packagist](https://packagist.org/packages/chimpmatic/mailchimp-webhook-handler)
- [GitHub](https://github.com/chimpmatic/mailchimp-webhook-handler)
- [Issues](https://github.com/chimpmatic/mailchimp-webhook-handler/issues)
- [Connect Contact Form 7 with Mailchimp](https://chimpmatic.com/connect-contact-form-7-with-mailchimp)
- [How to Get Your Mailchimp API Key](https://chimpmatic.com/how-to-get-your-mailchimp-api-key)
- [Mailchimp Audience Fields and Merge Tags](https://chimpmatic.com/mailchimp-audience-fields-and-merge-tags)
- [Chimpmatic — Contact Form 7 to Mailchimp](https://chimpmatic.com)

License
-------

[](#license)

MIT License. Copyright (c) 2026 [Chimpmatic](https://chimpmatic.com).

###  Health Score

40

—

FairBetter than 87% of packages

Maintenance95

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

53d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e0fe8014730461a907cfbc1b54ca0783ef523afa729ea89739cf96feaa78880e?d=identicon)[chimpmatic](/maintainers/chimpmatic)

---

Top Contributors

[![chimpmatic](https://avatars.githubusercontent.com/u/73747745?v=4)](https://github.com/chimpmatic "chimpmatic (1 commits)")

---

Tags

webhookmailchimpemail marketingsubscribecontact-form-7unsubscribemailchimp-apiwebhook-handler

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chimpmatic-mailchimp-webhook-handler/health.svg)

```
[![Health](https://phpackages.com/badges/chimpmatic-mailchimp-webhook-handler/health.svg)](https://phpackages.com/packages/chimpmatic-mailchimp-webhook-handler)
```

###  Alternatives

[activecampaign/api-php

Official PHP wrapper for the ActiveCampaign API.

1172.2M12](/packages/activecampaign-api-php)[kyon147/laravel-shopify

Shopify package for Laravel to aide in app development

473252.9k](/packages/kyon147-laravel-shopify)[pacely/mailchimp-apiv3

Simple API wrapper for Mailchimp API V3

95654.6k2](/packages/pacely-mailchimp-apiv3)[welp/mailchimp-bundle

MailChimp API V3 Symfony Bundle

45360.3k1](/packages/welp-mailchimp-bundle)[stymiee/authnetjson

Library that abstracts Authorize.Net's JSON APIs. This includes the Advanced Integration Method (AIM), Automated Recurring Billing (ARB), Customer Information Manager (CIM), Transaction Reporting, Simple Integration Method (SIM), and Webhooks.

19545.7k](/packages/stymiee-authnetjson)[kayedspace/laravel-n8n

A complete, expressive, and fluent Laravel client for the n8n public REST API and Webhooks Triggering.

1376.2k1](/packages/kayedspace-laravel-n8n)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)