Skip to main content

Webhooks

It might be more effective to get notified when specific data changes than polling continuously. That's what webhooks are meant to do.

Register a new webhook​

The first thing you need to do is to register a webhook. In other words, you will ask the Altoviz platform to call an URL that point to your service.

curl -iH "x-api-key:cddb5157-12be-42a9-985a-4501c6e6e2fa" \
-H "content-type: application/json" \
-X POST \
-d '{ "name": "Demo customers", "types": ["CustomerCreated", "CustomerUpdated", "CustomerDeleted"], "url": "https://hkdk.events/tLZ3N4TVcRVK" }' \
https://api.altoviz.com/v1/webhooks
caution

The URL needs to be public and accessible from Altoviz servers. So localhost or private networks will not work.

tip

During your development phase, you can services like Hookdeck to get a public endpoint for your local machine.

You can optionaly set a secretkey during registration. This secret key will be included in every calls so you can be sure that only the Altoviz API is calling your services.

🔍 REST API

Unregister a webhook​

When you no longer need to get notified, you can unregister a webhook.

curl -iH "x-api-key:cddb5157-12be-42a9-985a-4501c6e6e2fa" \
-X DELETE \
https://api.altoviz.com/v1/webhooks\?url\=https://hkdk.events/tLZ3N4TVcRVK

🔍 REST API

Listing webhooks​

Existing webhooks can be listed.

curl -iH "x-api-key: cddb5157-12be-42a9-985a-4501c6e6e2fa" https://api.altoviz.com/v1/Webhooks

🔍 REST API

Webhook types​

Each webhook has its own purpose. Theses are the webhook types supported:

TypeDescriptionHow to fire with the app
ContactCreatedFired after a contact was createdGo to https://app.altoviz.com/go/contacts and create a contact
ContactDeletedFired after a contact was deletedGo to https://app.altoviz.com/go/contacts and delete a contact
ContactUpdatedFired after a contact was updatedGo to https://app.altoviz.com/go/contacts and update a contact
CustomerCreatedFired after a customer was createdGo to https://app.altoviz.com/go/sales/customers and create a customer
CustomerDeletedFired after a customer was deletedGo to https://app.altoviz.com/go/sales/customers and delete a customer
CustomerUpdatedFired after a customer was updatedGo to https://app.altoviz.com/go/sales/customers and update a customer
InvoiceCreatedFired after an invoice was createdGo to https://app.altoviz.com/go/sales/invoices and create an invoice
InvoiceDeletedFired after an invoice was deletedGo to https://app.altoviz.com/go/sales/invoices and delete an invoice
InvoiceUpdatedFired after an invoice was updatedGo to https://app.altoviz.com/go/sales/invoices and update an invoice
QuoteCreatedFired after a quote was createdGo to https://app.altoviz.com/go/sales/quotes and create a quote
QuoteDeletedFired after a quote was deletedGo to https://app.altoviz.com/go/sales/quotes and delete a quote
QuoteUpdatedFired after a quote was updateGo to https://app.altoviz.com/go/sales/quotes and update a quote
ProductCreatedFired after a product was createdGo to https://app.altoviz.com/go/products and create a product
ProductDeletedFired after a product was deletedGo to https://app.altoviz.com/go/products and delete a product
ProductUpdatedFired after a product was updateGo to https://app.altoviz.com/go/products and update a product

Webhook calls​

When a webhook is fired, it will post data (webhook id, webhook type and entity content) to your registered URL.

{
  "id": "1233",
  "type": "CustomerCreated",
  "data": {
    "id": 370,
    "title": null,
    "lastName": null,
    "firstName": null,
    "email": "julien_fournier@intuit.com",
    "cellPhone": "01 43 57 91 28",
    "phone": null,
    "companyName": "Auchan hypermarché",
    "billingAddress": {
      "street": "1 Rue Abel Rabaud",
      "zipcode": "75011",
      "city": "Paris",
      "countryIso": "FR",
      "formattedAddress": "1 Rue Abel Rabaud\n75011 Paris\nFrance",
      "inlineAddress": "1 Rue Abel Rabaud, 75011 Paris, France"
    },
    "shippingAddress": null,
    "companyInformations": {
      "siret": "012345678",
      "vatNumber": null
    },
    "billingOptions": {
      "discount": {
        "type": "Percent",
        "value": 0.0
      },
      "vatReverseCharge": false,
      "vendorReference": null
    },
    "type": "Company",
    "number": "C001000"
  }
};

Security​

Altoviz generates signatures using a hash-based message authentication code (HMAC) with SHA-256 for you to check integrity. Here si how to check the signature.

Step 1 : Extract the signature from the header​

The signature is included into the X-SIGNATURE request header.

Step 2 : Calculate the signature​

Calculate an HMAC with the SHA256 hash function with your wehbook secret key as the key and the request body as the message.

Step 3 : Compare the signatures​

Check whether the calculated signature in step 3 is equal to the extracted signature in step 1.