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

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:

Type	Description	How to fire with the app
`ContactCreated`	Fired after a contact was created	Go to https://app.altoviz.com/go/contacts and create a contact
`ContactDeleted`	Fired after a contact was deleted	Go to https://app.altoviz.com/go/contacts and delete a contact
`ContactUpdated`	Fired after a contact was updated	Go to https://app.altoviz.com/go/contacts and update a contact
`CustomerCreated`	Fired after a customer was created	Go to https://app.altoviz.com/go/sales/customers and create a customer
`CustomerDeleted`	Fired after a customer was deleted	Go to https://app.altoviz.com/go/sales/customers and delete a customer
`CustomerUpdated`	Fired after a customer was updated	Go to https://app.altoviz.com/go/sales/customers and update a customer
`InvoiceCreated`	Fired after an invoice was created	Go to https://app.altoviz.com/go/sales/invoices and create an invoice
`InvoiceDeleted`	Fired after an invoice was deleted	Go to https://app.altoviz.com/go/sales/invoices and delete an invoice
`InvoiceUpdated`	Fired after an invoice was updated	Go to https://app.altoviz.com/go/sales/invoices and update an invoice
`QuoteCreated`	Fired after a quote was created	Go to https://app.altoviz.com/go/sales/quotes and create a quote
`QuoteDeleted`	Fired after a quote was deleted	Go to https://app.altoviz.com/go/sales/quotes and delete a quote
`QuoteUpdated`	Fired after a quote was update	Go to https://app.altoviz.com/go/sales/quotes and update a quote
`ProductCreated`	Fired after a product was created	Go to https://app.altoviz.com/go/products and create a product
`ProductDeleted`	Fired after a product was deleted	Go to https://app.altoviz.com/go/products and delete a product
`ProductUpdated`	Fired after a product was update	Go 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.