# Webhooks

Tip: Use a tool like webhook.site or RequestBin during development to inspect the raw webhook data before connecting your production system.

# Webhook Data Format

When a webhook fires, the platform sends structured data (in JSON format) to your webhook URL. If you are using an automation platform like Zapier or Make, it will parse this data for you automatically. If you are building a custom integration, here is what the data looks like:

{
  "event": "contact_tagged",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "contactId": "abc123xyz",
    "contactName": "Jane Smith",
    "contactPhone": "+15551234567",
    ...
  }
}

The data section varies depending on the event. For example, an appointment_booked event includes appointment details like date, time, and attendee information, while a new_message event includes the message text, which channel it came from, and who sent it.

# Agency Sub-Account Auto-Recharge Webhook

If you are an agency using a custom payment provider (instead of Stripe) for credit reselling, the platform can notify your server whenever a sub-account needs credits. Your server then processes the payment and calls the API to grant the credits.

To set this up, go to your agency Reselling settings and enter your webhook URL in the Auto-Recharge Webhook section. For the non-technical overview, see Agency Accounts.

# Event name

agency_sub_account_auto_recharge

# When it fires

This webhook is sent when a sub-account’s credit balance drops below their configured auto-recharge threshold.

# Payload format

{
  "event": "agency_sub_account_auto_recharge",
  "sub_account_id": "<firebase-uid>",
  "sub_account_email": "[email protected]",
  "sub_account_name": "John Doe",
  "agency_id": "<firebase-uid>",
  "credits_requested": 500,
  "current_balance": 42,
  "threshold": 100,
  "price_per_credit_cents": 10,
  "price_per_credit_currency": "usd",
  "total_amount_cents": 5000,
  "timestamp": "2026-04-13T12:00:00.000Z",
  "idempotency_key": "auto_recharge_abc123_1681387200000"
}

# What to do after receiving this webhook

1. Verify the request — Check the idempotency_key to make sure you have not already processed this recharge.
2. Process payment — Charge the sub-account using your payment provider (card charge, invoice, balance deduction, etc.).
3. Grant credits — Call the API to add credits to the sub-account. See API Access — Grant Credits to a Sub-Account for the exact request format.
4. Return a success response — Respond with an HTTP 200 status code to acknowledge receipt.

# Important notes

• 5-minute cooldown: After a webhook is sent for a sub-account, the platform will not send another one for the same sub-account for at least 5 minutes, even if their balance drops further. This prevents duplicate charges during processing.
• Use the idempotency key: Always check the idempotency_key before granting credits. If your server crashed after granting credits but before responding, the platform may resend the webhook on the next credit drop.
• Failures are safe: If your webhook URL is unreachable or returns an error, no credits are granted and nothing breaks. The system will send a new webhook the next time the sub-account’s balance drops below the threshold.

# Webhook Reliability

• The platform sends webhooks over a secure connection (HTTPS). Make sure the web address you provide uses HTTPS.
• If your system returns an error, the delivery is considered failed.
• Monitor your receiving system’s uptime to avoid missing events.
• For critical workflows, consider building in a fallback mechanism (for example, periodically checking the app for missed events).

# Troubleshooting

# Next Steps

• GoHighLevel Integration - Use webhooks to integrate the platform with GHL.
• API Access - Combine webhooks with the API for powerful automations.
• Creating Tags - Set up tags that trigger your webhooks.