Skip to main content
Webhooks notify your application when billing events occur in Alguna. Set up webhooks to get instant updates when invoices are issued, payments processed, and subscriptions change.

​
How Webhooks Work

When an event occurs (like an invoice being paid), Alguna sends a notification to a URL you specify. Your application can then take action based on that event.

​
Setting Up Webhooks

​
Step 1: Add a Webhook Endpoint

  1. Navigate to Settings → Webhooks
  2. Click Add Endpoint
  3. Enter your webhook URL (provided by your development team)
  4. Click Save

​
Step 2: Select Events

Choose which events you want to receive:
  1. Click on your endpoint
  2. Select the events you want to subscribe to
  3. Click Save

​
Step 3: Copy the Webhook Secret

  1. After saving, copy the Webhook Secret
  2. Share this with your development team for signature verification
The webhook secret is only shown once. Copy it immediately and store it securely.

​
Available Events

​
Subscription Events

EventWhen It’s Sent
subscription.activatedA subscription becomes active
subscription.startedA subscription reaches its start date
subscription.cancelation_scheduledA cancellation is scheduled
subscription.canceledA subscription is canceled

​
Invoice Events

EventWhen It’s Sent
invoice.issuedAn invoice is sent to a customer
invoice.paidAn invoice is fully paid

​
Payment Events

EventWhen It’s Sent
payment.createdA payment is initiated
payment.updatedA payment status changes

​
Credit Events

EventWhen It’s Sent
account.credits.grantedCredits are added to a customer
account.credits.balance_depletedA customer’s credit balance reaches zero

​
Other Events

EventWhen It’s Sent
checkout.session.completedA checkout is completed
refund.updatedA refund status changes

​
Testing Webhooks

Send test events to verify your setup:
  1. Go to Settings → Webhooks
  2. Select your endpoint
  3. Click Send Test Event
  4. Choose an event type
  5. Verify the event was received

​
Viewing Webhook History

Track webhook deliveries:
  1. Go to Settings → Webhooks
  2. Select your endpoint
  3. Click Message Logs
  4. View delivery status, timestamps, and responses

​
Retry Policy

If delivery fails, Alguna retries automatically:
AttemptWait Time
1Immediate
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
After 7 failed attempts over 5 days, the endpoint is disabled.

​
Troubleshooting

​
Webhook Not Received

  1. Check the endpoint URL is correct
  2. Verify the endpoint is publicly accessible
  3. Review Message Logs for error details
  4. Ensure your server responds within 15 seconds

​
Endpoint Disabled

  1. Check Message Logs for failure reasons
  2. Fix any issues with your endpoint
  3. Click Enable to reactivate

​
Best Practices

Test First

Use test events before going live.

Monitor Logs

Regularly check webhook logs for failures.

Secure Secrets

Never expose your webhook secret publicly.

Quick Response

Ensure your endpoint responds within 15 seconds.

​
Next Steps

Event Reference

See all webhook events and payloads.

Automations

Automate workflows based on events.