Skip to main content

​
How Webhooks work

When an event occurs in FunnelFox Payments, FunnelFox Payments sends an HTTP POST request to your configured endpoint with a JSON payload containing event details. The same event is also recorded and displayed in the Webhook Events block of your FunnelFox Payments dashboard for visibility and troubleshooting. There are two webhook event flows in FunnelFox Payments: Events triggered by customer actions Events triggered by your team in the dashboard

​
Get started

1

Add your webhook URL

Go to Settings > Webhooks in your FunnelFox Payments dashboard. Paste your endpoint into New Value of the sender_task_targets.first.url setting, shown as Webhook (1) url.Click Save, then confirm the change.
You can include query parameters in the URL for example, to pass an environment.
2

(Optional) Turn on signatures

Add a secret to the sender_task_targets.first.signing_secret setting (Webhook (1) signing_secret) to enable signature verification.Learn about verification.
3

Handle events

Parse the JSON payload and return a 2xx response (for example 200) to acknowledge it.
4

Deduplicate deliveries

Webhooks may be retried. Use event_timestamp from the payload as a unique key to detect and ignore duplicate events.
5

(Optional) Add additional URLs

Use additional targets, such as sender_task_targets.second.url (Webhook (2) url), if you want to send webhooks to multiple destinations, for example production and sandbox. You can configure up to seven targets.

​
Event types

FunnelFox Payments sends webhooks for these events:

Order events

Subtypes:
  • settled - Payment completed successfully
  • declined - Payment failed or was rejected
  • success - Order reached its first paid state (off by default)

Subscription events

Subtypes:
  • starting_trial - Trial period starts
  • convertion - Trial converts to paid subscription
  • renewing - Subscription renews (regular charge)
  • unsubscription - User cancels subscription (auto-renewal disabled)
  • planning_postponed_subscription - Subscription with UPCOMING status scheduled to start when delayed_start migration is used
  • pausing - Subscription paused
  • defering - Next charge date postponed
  • resuming - Paused subscription resumes
  • recovering_autorenew - Auto-renewal restored after failure
  • expiration - Subscription expired
  • unknown - Unknown or unclassified event
  • start_grace - Grace period starts after failed charge
  • start_retry - Retry attempts start without grace period
  • finish_grace - Grace period ends
  • recovering - Recovered from grace/retry state

One-off events

Subtypes:
  • granted - Access granted
  • revoked - Access revoked

Refund events

refund - Sent when a refund is completed for an order.

User events

Subtypes:
  • update_email - User’s email address was updated

Dispute events

Subtypes:
  • opened - A dispute was registered for an order
All events include the full state of related objects (subscription, order, user) in the payload, allowing you to sync your system without additional API calls.
See the FunnelFox Payments webhook reference for complete payload schemas.

​
Order success event

The success order subtype lets you act on an order the moment it first reaches a paid state, instead of waiting for settlement to finish. Use it when you want to grant access or provision faster. When enabled, FunnelFox Payments sends one success event per order as soon as the order reaches its first paid state (authorized, settling, or settled), and it replaces the settled event for that webhook target. The event is off by default.
Even when the top-level subtype is success, the order.status field in the payload still reflects the order’s real status at the moment the event is sent, so it can be authorized, settling, or settled.
To enable the success order event:
  1. Go to Settings > Webhooks in your FunnelFox Payments dashboard.
  2. Find the sender_task_targets.first.use_order_success_event setting (Webhook (1) emit success event on authorized/settling) and set its New Value to Enabled. Other targets use the matching setting, such as sender_task_targets.second.use_order_success_event.
  3. Click Save, then confirm the change.

​
Verification

FunnelFox Payments supports webhook signature verification to ensure requests are authentic. To enable signature verification:
  1. Go to Settings > Webhooks in your FunnelFox Payments dashboard.
  2. Add a secret key to the sender_task_targets.first.signing_secret setting (Webhook (1) signing_secret).
  3. Click Save, then confirm the change.
FunnelFox Payments will include an ff-webhook-signature header with each webhook request containing an HMAC SHA-256 signature of the payload. Optionally, you can verify the signature by computing the HMAC SHA-256 hash of the raw request body using your secret key and comparing it to the received signature. For example:

​
Retry logic

If your endpoint fails to respond with a 2xx status code (for example, server downtime or errors), FunnelFox Payments automatically retries delivery up to 6 times with exponential backoff.

​
Retry schedule

FunnelFox Payments uses the following retry intervals (in seconds):
This results in approximately:
  • Attempt 1: ~8 seconds
  • Attempt 2: ~1 minute
  • Attempt 3: ~8.5 minutes
  • Attempt 4: ~1.1 hours
  • Attempt 5: ~9 hours
  • Attempt 6: ~72 hours (3 days)
Delivery is considered successful when your endpoint returns any HTTP 2xx status code. Retries continue until success or the maximum number of attempts is reached.

​
Failed deliveries

You can view webhook deliveries and their retry details in the Webhook Events block of a customer’s page in your FunnelFox Payments dashboard. Failed deliveries have the sent_failed status. Click a delivery to see its Delivery report, Payload, and Headers (masked). To see failed deliveries across all customers, go to Operations > Webhook delivery failures.
Failed webhook delivery in the Webhook Events block

​
Rate limits

Detailed documentation is coming soon!