Skip to main content

Webhooks

Webhooks allow you to notify external services when certain events occur in Invoiless.

Security​

To validate the signature you received from Invoiless, you can generate the signature using your secret and compare it with the signature you received in the request.

  1. Using the HMAC SHA-256 algorithm, create a hash of the entire received payload as binary.
  2. Encode the binary hash in base64 format.
  3. Add prefix sha256= to the binary hash.
  4. Compare the created value with the signature you received in the invoiless-signature header from Invoiless.

Node.js Example​

const crypto = require('crypto');

function isValidSignature(req) {
  const signature = req.headers['invoiless-signature'];
  const hash = crypto
    .createHmac('sha256', process.env.INVOILESS_SECRET)
    .update(req.rawBody)
    .digest('base64');

  return signature === `sha256=${hash}`;
}

Payload​

The body of the webhook will be in JSON format:

{
  "type": "EventType",
  "data": {
    // ...
  }
}

Notes​

  • To confirm receipt of a webhook event, your server endpoint should return a 200 OK HTTP status code. Any other HTTP response code will be treated as a failure.
  • Invoiless waits for a maximum of 10 seconds for your server to respond to the HTTP POST request.

Event Types​

You can configure your webhook to be triggered by the following events:

Invoice Events​

EventDescription
InvoiceCreatedAn invoice was created
InvoiceUpdatedAn invoice was updated
InvoicePaidAn invoice was paid
InvoiceDeletedAn invoice was deleted
InvoiceSentAn invoice was sent to a customer
InvoiceOverdueAn invoice became overdue
ReminderSentA payment reminder was sent
LateFeeAppliedA late fee was applied to an invoice

Estimate Events​

EventDescription
EstimateCreatedAn estimate was created
EstimateUpdatedAn estimate was updated
EstimateDeletedAn estimate was deleted
EstimateAcceptedAn estimate was accepted
EstimateSentAn estimate was sent to a customer

Transaction Events​

EventDescription
TransactionCreatedA transaction was created
TransactionUpdatedA transaction was updated
TransactionDeletedA transaction was deleted

Payment Events​

EventDescription
PaymentCreatedA payment was created
PaymentUpdatedA payment was updated
PaymentDeletedA payment was deleted

Refund Events​

EventDescription
RefundCreatedA refund was created
RefundUpdatedA refund was updated
RefundDeletedA refund was deleted

Customer Events​

EventDescription
CustomerCreatedA customer was created
CustomerUpdatedA customer was updated
CustomerDeletedA customer was deleted

Recurring Invoice Events​

EventDescription
RecurringCreatedA recurring invoice template was created
RecurringUpdatedA recurring invoice template was updated
RecurringDeletedA recurring invoice template was deleted
RecurringInvoiceGeneratedAn invoice was generated from a recurring template