API: salvaWebhook

Descrizione

Il metodo salvaWebhook permette di registrare o aggiornare un endpoint webhook associato al proprio account API.

Quando si verifica uno degli eventi selezionati, FattureWeb invia una richiesta POST all'URL indicato.

Alla creazione del webhook viene restituito un secret. Il secret serve per verificare la firma delle notifiche ricevute e viene mostrato solo nella risposta di creazione o quando viene rigenerato.

Parametri

  • url (obbligatorio): URL HTTPS che riceverà le notifiche webhook.
  • events (opzionale): lista degli eventi da notificare. Se non indicata, vengono abilitati tutti gli eventi disponibili.
  • enabled (opzionale): 1 per abilitare il webhook, 0 per salvarlo disabilitato.
  • webhook_id (opzionale): se indicato, aggiorna il webhook esistente.
  • reset_secret (opzionale): se vale 1, rigenera il secret del webhook.

Chiamata API

La chiamata deve essere effettuata tramite POST all'endpoint:

https://www.fattureweb.com/api/

Esempio di Chiamata POST

{
    "action": "call",
    "key": "LA_TUA_API_KEY",
    "code": "abcdef",
    "payload": {
        "api_name": "Webhook",
        "method": "salvaWebhook",
        "input": {
            "url": "https://cliente.it/api/fattureweb/webhook",
            "events": [
                "fattura.stato_aggiornato",
                "fattura.scartata",
                "fattura_passiva.ricevuta"
            ],
            "enabled": 1
        }
    }
}

Esempi di Codice


$url = 'https://www.fattureweb.com/api/';

$payload = array(
    'api_name' => 'Webhook',
    'method' => 'salvaWebhook',
    'input' => array(
        'url' => 'https://cliente.it/api/fattureweb/webhook',
        'events' => array(
            'fattura.stato_aggiornato',
            'fattura.scartata',
            'fattura_passiva.ricevuta'
        ),
        'enabled' => 1
    )
);

$data = array(
    'action' => 'call',
    'key' => 'LA_TUA_API_KEY',
    'code' => 'abcdef',
    'payload' => json_encode($payload)
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
curl_close($ch);

echo $result;
                    

import json
import requests

url = 'https://www.fattureweb.com/api/'

payload = {
    'api_name': 'Webhook',
    'method': 'salvaWebhook',
    'input': {
        'url': 'https://cliente.it/api/fattureweb/webhook',
        'events': [
            'fattura.stato_aggiornato',
            'fattura.scartata',
            'fattura_passiva.ricevuta'
        ],
        'enabled': 1
    }
}

data = {
    'action': 'call',
    'key': 'LA_TUA_API_KEY',
    'code': 'abcdef',
    'payload': json.dumps(payload)
}

response = requests.post(url, data=data)
print(response.text)
                    

Risposta di Successo

{
    "code": "200",
    "result": {
        "status": "success",
        "message": "Webhook registrato correttamente",
        "webhook_id": 1,
        "url": "https://cliente.it/api/fattureweb/webhook",
        "events": [
            "fattura.stato_aggiornato",
            "fattura.scartata",
            "fattura_passiva.ricevuta"
        ],
        "enabled": 1,
        "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "secret_note": "Conserva questo secret: verrà mostrato solo ora"
    }
}
Attenzione: il secret va salvato dal cliente. Per motivi di sicurezza non verrà mostrato nelle chiamate successive di lista.