Skip to main content

Webhooks

Webhooks enable real-time integrations by sending HTTP notifications when specific events occur in Mambo. These automated notifications allow you to build responsive integrations that can update user interfaces, trigger notifications, or process data as soon as events happen.

Prerequisites​

  • A publicly accessible HTTPS endpoint to receive webhook events
  • Basic understanding of HTTP and JSON
  • Mambo API access

Common use cases​

  • Send congratulatory emails when users earn achievements
  • Update leaderboards in real-time
  • Trigger push notifications for mission completions
  • Sync user data with external systems
  • Track user engagement metrics

Security best practices​

  • Use HTTPS endpoints only
  • Validate webhook signatures
  • Store webhook secret keys securely

Payload Version​

When you configure a webhook, the Payload Version field controls which version of the event payload Mambo sends to your endpoint:

  • Pinned — the payload is locked to your account's pinned API version. Future Mambo upgrades won't change the payload structure until you upgrade your pinned version.
  • Latest — the payload always uses the latest version available on the server, and will change automatically when Mambo is upgraded.

Example​

Your account is pinned to 8.0.3 and the server is running 8.10.2. The PointWalletUpdated event currently delivers:

{ "exampleField": "value" }

In a future Mambo 9.0.0 release, a breaking change renames the field:

{ "newExampleField": "value" }

With Pinned, your webhook keeps receiving the original exampleField payload after the upgrade — until you decide to upgrade your pinned version. With Latest, your webhook immediately switches to newExampleField as soon as the server is upgraded.

This holds even for event types introduced after your pinned version: "Pinned" protects you from future payload changes regardless of when the event itself was added.

For production integrations, use Pinned. See Webhook versioning for the full technical details.

Troubleshooting​

  • Verify your endpoint is publicly accessible
  • Check webhook logs in the Mambo dashboard
  • Monitor webhook response times
  • Validate payload signatures

For detailed technical specifications, see our webhook API documentation.