Skip to content

Partner Webhooks (Billing & Entitlements) ​

Receive subscription/entitlement events from your billing system. When a user becomes eligible for AddMaple, AddMaple can automatically send an invitation email.

Endpoint: POST https://addmaple.com/api/v1/partner/[partnerId]/webhooks/[provider]

Example: POST https://addmaple.com/api/v1/partner/acme/webhooks/billing

Authentication ​

Use an HTTP auth scheme supported by your provider (commonly Basic or Bearer). AddMaple validates requests using partner-specific webhook credentials configured during setup.

Send the provider payload as-is (raw JSON) in the request body.

Setup & Mapping (Required) ​

Webhook payloads vary by provider. During setup, we’ll ask you for mapping information so AddMaple can consistently extract the fields below from your raw webhook events.

At minimum, AddMaple needs to derive:

  • Event type: created/changed/cancelled/deleted (or equivalent)
  • Account/user identifier: a stable identifier we can map to a person (your internal user id, account id, or customer id)
  • Email (optional but recommended): used to send the invite email when we don’t already have an email on file
  • Plan/entitlement: which plan, SKU, tier, or entitlement changed
  • Eligibility flag: how to determine whether a plan/entitlement should trigger an invite
  • Effective time: when the change should take effect (immediate vs end-of-term), if your provider differentiates
  • Idempotency key: a unique event id so retries don’t create duplicate invites

Once configured, AddMaple will accept the raw events and apply your mapping to trigger the appropriate AddMaple action (including sending invitation emails for eligible upgrades).

Supported Events ​

  • subscription_created – Create invite and send invitation email (if eligible plan)
  • subscription_changed – Same as above for eligible plans
  • subscription_cancelled / subscription_deleted – Cancel pending invite, schedule downgrade at term end

Response ​

Returns 200 OK to acknowledge receipt. Most providers retry on non-2xx responses.

Partner Documentation