Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fungies.io/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let your application receive real-time notifications when events occur in your Fungies account. Instead of polling the API, Fungies pushes event data directly to your server.

​
Why Use Webhooks?

Webhooks are essential for building reactive integrations:
  • Fulfill orders automatically - Deliver digital products when a payment succeeds
  • Sync with your database - Keep your user records up-to-date with subscription changes
  • Trigger workflows - Send confirmation emails, update inventory, or notify your team
  • Handle async events - Respond to events that happen outside of direct API calls

​
How It Works

  1. An event occurs (e.g., order.paid)
  2. Fungies sends an HTTP POST request to your webhook URL
  3. Your server processes the event and returns a 2xx response
  4. Fungies marks the delivery as successful

​
Event Payload

Each webhook delivers a JSON payload containing an Event object: 
{
  "object": "event",
  "id": "evt_abc123",
  "type": "order.paid",
  "createdAt": 1704067200000,
  "data": {
    "object": "order",
    "id": "ord_xyz789",
    // ... order details
  }
}

​
Subscription checkouts and fulfillment

New subscriptions emit two separate events from different stages of checkout. They can arrive in either order.
EventWhen it firesUse for fulfillment?
subscription_createdStripe creates the subscription object (often while the first payment is still PENDING)No — informational only unless data.lastPayment.status is PAID
payment_successThe initial or renewal payment is confirmed (PAID)Yes — grant access, deliver goods, sync your database
Do not fulfill subscription purchases on subscription_created alone when data.lastPayment.status, data.order.status, or data.subscription.status is PENDING or incomplete. Wait for payment_success, or ignore the event until payment fields show PAID / active.
Enable payment_success on every webhook endpoint that fulfills orders. If only subscription_created is selected, you will not receive a paid signal when checkout completes. For renewals, use payment_success (initial and interval charges) or subscription_interval depending on your integration; the initial signup should always key off payment_success for the first charge.

​
Delivery Guarantees

Fungies guarantees at-least-once delivery for all webhook events. Your endpoint should handle potential duplicate events idempotently.
BehaviorDetails
ProtocolHTTPS (required for production)
MethodPOST
Expected response2xx status code
Retry attempts5 times on failure
Timeout30 seconds

​
Securing Your Webhooks

Every webhook request includes an x-fngs-signature header containing an HMAC-SHA256 signature. Use your webhook secret to verify that requests actually came from Fungies. 
x-fngs-signature: sha256_6808ed5be1262b60818359fa586145810d0793e8a677f1326520d3844e21b640
Always verify webhook signatures in production. This prevents attackers from sending fake events to your endpoint.

​
Next Steps

Set Up Webhooks

Create your webhook endpoint and register it with Fungies

Test Webhooks

Test your integration locally with ngrok or webhook.site