Fiscal Harmony API
    Fiscal Harmony API
    • Introduction
    • Authentication
    • Data
    • Webhooks
    • Support
    • Account
      • Get Profile
        GET
      • Get Fiscal Device
        GET
      • Subscription
        GET
    • Transactions
      • Submit Invoice
        POST
      • Submit Credit Note
        POST
      • Check Status
        POST
      • Download Pdf
        GET
    • Mappings
      • Tax Mappings
        • Get All TaxMappings
        • Add Tax Mapping
        • Get Specific Tax Mapping
        • Update Tax Mapping
        • Delete Tax Mapping
      • Currency Mappings
        • Supported Currencies
        • Get All CurrencyMappings
        • Add Currency Mapping
        • Get Specific Currency Mapping
        • Update Currency Mapping
        • Delete Currency Mapping
    • Schemas
      • Account
        • Profile
        • FiscalDevice
        • DeviceConfig
        • ApplicableTax
        • BillingPlan
        • BillingStatus
        • Subscription
      • Mappings
        • CurrencyMapping
        • TaxMapping
      • Transactions
        • Invoice
        • CreditNote
        • BuyerContact
        • PaymentMethodType
        • LineItem
        • StatusRequest
      • Date

    Webhooks

    Webhooks#

    Webhooks allow you to subscribe to invoice/credit note processing events that happen in Fiscal Harmony. When one of these events are triggered we’ll send a HTTP POST payload to the webhook’s configured URL.
    Webhooks can be created on all API Keys and are found on the API Key menu underneath the API Key and secret.
    To add a webhook, simply add a valid HTTPS URL in the input field below and click Save & Test Webhook URL. Test data will be sent to your webhook URL and the webhooks are activated on receiving responses which have been correctly processed. The status should change to "Webhook Active" and you will start receiving events on your URL you provided.

    Server Setup for Webhooks#

    Once you’ve created the webhook you’ll need to set up your server to receive the HTTP POST requests at the endpoint you specified.
    There are just a few basic things that we expect from your endpoint:
    1.
    It uses HTTPS on the standard 443 port
    2.
    It responds within 5 seconds with a 2xx status code
    3.
    There are no cookies in the response headers
    4.
    If the signature is invalid a 401 Unauthorised status code is returned
    If we don’t receive an acceptable response when sending events we will continue retrying the request, with decreasing frequency for up to 24 hours. After 24 hours the webhook will be disabled and needs to be re-enabled in the online user account.
    If you want to test webhooks in your local dev environment, GitHub has a handy guide using Sinatra and ngrok.

    Save & Test Webhook URL#

    To ensure the requests you receive are coming from Fiscal Harmony you need to verify the signature provided in the X-Api-Signature header. When creating or re-enabling a webhook subscription (or updating the subscription URL) the user will be prompted to Save & Test Webhook URL validation. This validation process will be a series of HTTPS POST requests to the URL provided in the Webhook URL field.
    If the payload is hashed using HMACSHA256 with your API Secret and base64 encoded, it should match the signature in the header. This is a correctly signed payload. If the signature does not match the hashed payload it is an incorrectly signed payload. To gain “Save & Test Webhook URL” validation, the receiving URL must respond with a 2xx status for all correctly signed payloads and status: 401 Unauthorized for all incorrectly signed payloads. It must also respond within the guidelines of all webhook requests listed above. If the validation is passed, the status displayed in the console will change from Webhook Inactive to Webhook Active. If the validation fails, the status will return to Webhook Inactive.

    Delivery Failures#

    When you fail to respond correctly to a webhook we will immediately retry. Any subsequent retry attempts will exponentially back-up at 2 minutes, 20 minutes, 2 hours until a successful response is given.
    If after 24 hours we still have not received a successful response we will disable your webhook subscription. Once the issue has been resolved you can re-enable your webhook subscription and you may be able to click Save & Test Webhook URL for process to continue receiving your webhooks. Any events that happen while your subscription is in the Retry or Disabled states will be saved for up to 24 hours and replayed in order once your subscription is healthy again.
    Modified at 2026-03-02 07:18:30
    Previous
    Data
    Next
    Support
    Built with