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. chimpmatic/mailchimp-webhook-handler

ActiveLibrary

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

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

v1.0.0(6d ago)00MITPHPPHP &gt;=8.5

Since Mar 17Pushed 6d 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 today

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 &lt; 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 88% of packages

Maintenance98

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

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

6d 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

[spatie/laravel-webhook-server

Send webhooks in Laravel apps

1.1k8.4M19](/packages/spatie-laravel-webhook-server)[activecampaign/api-php

Official PHP wrapper for the ActiveCampaign API.

1172.1M11](/packages/activecampaign-api-php)[shopify/shopify-api

Shopify API Library for PHP

4604.6M11](/packages/shopify-shopify-api)[php-mqtt/client

An MQTT client written in and for PHP.

4502.0M21](/packages/php-mqtt-client)[symfony/webhook

Eases sending and consuming webhooks

562.8M28](/packages/symfony-webhook)[scullwm/mailhookbundle

A bundle to catch API webhook from differents mail service

4020.5k](/packages/scullwm-mailhookbundle)

PHPackages © 2026

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