Tip Top Jar now lets creators hook their own backend systems directly into the tip flow. By configuring a Callback URL, the platform sends a JSON payload to your endpoint via an HTTP POST request the moment a tip lands. This guide walks you through setting it up and testing it.
1. What the Callback URL Does
When a visitor tips you, Tip Top Jar instantly fires a webhook to the URL you specify. The request contains all the essential details of the tip, plus any query parameters you attached to the public Tip Top Jar link. With this data you can:
- Store the tip in your own database
- Trigger a thank‑you email, SMS, or Discord notification
- Feed the event into an analytics pipeline or CRM
- Tie the tip to a specific user, session, or marketing campaign
Because the request is pushed from our servers, there’s no polling or delay. In other words, your workflow runs the second the tip is confirmed.
2. Payload Structure
| Field | Type | Description |
|---|---|---|
| Tipper_Name | string | Name entered by the donor. If omitted, defaults to “Tipper”. |
| Recipient_Account | string | Your Tip Top Jar username (the account that receives the tip). |
| Amount | number | Numeric tip amount. |
| Currency | string | ISO‑4217 currency code (e.g., USD, EUR). |
| Timestamp | string | Milliseconds since the Unix epoch (ISO‑format) when the tip occurred. |
| UrlQueryParams | string | The raw query‑string that was appended to your public Tip Top Jar URL (e.g., user_id=1234&campaign=new‑user‑tip). |
Example payload
{
"Tipper_Name": "Alice",
"Recipient_Account": "OmarA",
"Amount": 10,
"Currency": "USD",
"Timestamp": "1761865284136",
"UrlQueryParams": "user_id=1234&campaign=new-user-tip"
}
3. Adding a Callback URL
- Log in to your Tip Top Jar dashboard.
- Navigate to Settings.
- Go to the Custom callback URL field.
- Enter the full HTTPS endpoint you want us to call (e.g.,
https://example.com/ttj/webhook). - Click Save.
Note: Only HTTPS URLs with a valid TLS certificate are accepted. Self‑signed certificates will be rejected.
4. Tracking Users with URL Parameters
To associate tip events with specific users, sessions, or campaigns, append query parameters to your Tip Top Jar URL before sharing it.
For example:
https://tiptopjar.com/remi?user_id=1234&campaign=new-user-tip
These query parameters are returned in the UrlQueryParams field of the webhook payload:
{
"Tipper_Name": "Alice",
"Recipient_Account": "OmarA",
"Amount": 10,
"Currency": "USD",
"Timestamp": "1761865284136",
"UrlQueryParams": "user_id=1234&campaign=new-user-tip"
}
When to use URL parameters
- Identify the tipper – track which user or session made the tip.
- Measure campaign performance – see which referral source generated the most tips.
- Sync with your backend – push the data straight into your analytics or CRM.
- Trigger custom workflows – e.g., send a personalized thank‑you message.
5. Testing the Integration
- Generate a temporary endpoint using a service like Webhook.site.
- Paste that URL into the Callback URL field in your settings page.
- Click on Send test.
- You should see a POST request with the JSON payload in the receiving server terminal.
9. TL;DR
- Add an HTTPS endpoint in Settings.
- Test with a service like Webhook.site.
- Integrate into your flow.
That’s all you need to start receiving tip data in real time and unlock powerful automation for your community.
Need a Hand?
If anything isn’t clear, reach out to our customer care. We’re happy to walk you through the setup step‑by‑step.
Till next time, best of luck!