Alguna provides webhooks to notify you about events that happen in your account. Webhooks are a way to receive real-time notifications when an event occurs in Alguna. Webhooks are particularly useful for asynchronous events like when a new customer is created, a quote is activated, or an invoice is paid.

​

Format

Alguna follows the Standard Webhooks specification for its webhooks. The payload of the webhook will be a JSON object with the following structure:

{
  "type": "invoice.issued",
  "timestamp": "2024-08-03T20:26:10Z",
  "data": {
    "id": "someid",
    ...
  }
}

• type - The type of event that occurred. The type will be a string that represents the event that occurred. For example, invoice.paid, quote.activated
• timestamp - The time at which the event occurred as an RFC3339 string (e.g. "2024-08-03T20:26:10Z").
• data - The data associated with the event. This will be a specific shape of object, depending on the event type.

All date/time fields in webhook payloads are strings in RFC3339 format.

​

Objects

​

Invoice

{
  "id": "ZVzWRFnt",
  "accountId": "aBsZxlLh",
  "currency": "USD",
  "description": "Platform subscription",
  "billingPeriodStart": "2024-08-01T00:00:00Z",
  "billingPeriodEnd": "2024-08-29T23:59:59Z",
  "status": "upcoming",
  "total": "200.00",
  "createdAt": "2024-01-24T16:36:52Z",
  "updatedAt": "2024-01-26T19:30:37Z"
}

​

Payment

{
  "id": "ZVzWRFnt",
  "accountId": "aBsZxlLh",
  "invoiceId": "dfTDjGsA",
  "currency": "USD",
  "amount": "200.00",
  "status": "completed",
  "createdAt": "2024-01-24T16:36:52Z",
  "updatedAt": "2024-01-26T19:30:37Z"
}

Payment status can be one of the following:

• pending_client_action - The payment has been initiated but requires additional information or action from the customer to proceed (such as completing verification, providing billing details, or confirming the transaction).
• pending_authorization - The payment is awaiting approval from the payment processor or financial institution before it can be processed.
• processing - The payment is actively being processed, typically used for asynchronous payment methods where completion isn’t immediate.
• completed - The payment has been successfully processed.
• failed - The payment could not be completed due to an error, insufficient funds, declined authorization, or other issues.

​

Supported Events

Currently, Alguna supports the following events:

• invoice.issued - Sent when an invoice is issued. Returns the invoice object.
• invoice.paid - Sent when an invoice is paid. Returns the invoice object.
• payment.created - Sent when a payment is first created. Returns the payment object.
• payment.updated - Sent when a payment is updated. Returns the payment object.

​

Example

Combining the Standard Webhooks specification above, alongside the Invoice object, gives us the complete payload:

{
  "type": "invoice.issued",
  "timestamp": "2022-11-03T20:26:10Z",
  "data": {
    "id": "ZVzWRFnt",
    "accountId": "aBsZxlLh",
    "currency": "USD",
    "description": "Platform subscription",
    "billingPeriodStart": "2024-02-01T00:00:00Z",
    "billingPeriodEnd": "2024-02-29T23:59:59Z",
    "status": "upcoming",
    "total": "200.00",
    "createdAt": "2024-01-24T16:36:52Z",
    "updatedAt": "2024-01-26T19:30:37Z"
  }
}

​

Responding to Webhooks

The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s). It’s also important to disable CSRF protection for this endpoint if the framework you use enables them by default.

​

Verifying Webhooks

Webhook signatures is your way to verify that webhook messages are sent by us. For a more detailed explanation, check out this article on why you should verify webhooks.

​

Authenticating webhook signatures

To verify your webhooks, you will need to use the secret key that is provided in your account settings, along with headers and the payload that was sent to you.

Our webhook partner Svix offers a set of useful libraries that make verifying webhooks very simple. Here is a an example using Javascript:

import { Webhook } from "svix";

const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw";

// These were all sent from the server
const headers = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
};
const payload = '{"test": 2432232314}';

const wh = new Webhook(secret);
// Throws on error, returns the verified content on success
const payload = wh.verify(payload, headers);

​

IP Whitelist

In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from Svix’s IP addresses.

52.215.16.239
54.216.8.72
63.33.109.123

​

Retries

We attempt to deliver each webhook message based on a retry schedule with exponential backoff. Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

​

Disabling failing endpoints

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled.