# 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.

```bash
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](https://hookdeck.com/) 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](/api#tag/webhooks/post/v1/Webhooks)

## Unregister a webhook

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

```bash
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](/api#tag/webhooks/delete/v1/Webhooks)

## Listing webhooks

Existing webhooks can be listed.

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

[🔍 REST API](/api#tag/webhooks/get/v1/Webhooks)

## 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.

```json
{
  "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.