Un webhook è una URL vostra a cui facciamo una POST quando succede qualcosa su un account connesso — arriva un messaggio, si aggiunge un collegamento, un account chiede attenzione. Sostituisce l'interrogazione a ciclo, che su un'API con limiti d'uso non è una preferenza di stile ma la differenza fra funzionare e non funzionare.
Verificate la firma. Ogni volta.
Il vostro endpoint sta sull'internet pubblico, e qualunque cosa riesca a raggiungerlo può pubblicarci quello che vuole. Ogni consegna porta una firma calcolata da un segreto che abbiamo solo voi e noi; controllatela prima di leggere il corpo, e confrontatela a tempo costante invece che con un'uguaglianza di stringhe che esce in anticipo.
Aspettatevi lo stesso evento due volte
La consegna è almeno una volta. Se il vostro endpoint è lento, risponde 500, o anche solo sembra farlo, lo stesso evento arriva di nuovo. Non è un difetto da segnalare; è il contratto. Rendete il gestore idempotente e il problema sparisce.
Rispondete 200 in fretta e fate il lavoro dopo. Un gestore che passa dieci secondi a chiamare altre API prima di rispondere è un gestore che verrà ritentato mentre sta ancora lavorando.
Domande frequenti
Il mio assistente non ha un server. Può ricevere webhook?
Sì, tramite la posta in arrivo dell'IA: un webhook che teniamo per la vostra IA invece di inviarlo da qualche parte. Conserva per 30 giorni ogni evento sui vostri account collegati, e un assistente, o un agente di stanza con MakeHybrid spuntato, la legge quando glielo si chiede.
Un webhook può avviare un agente IA in una stanza di progetto?
Non direttamente, perché le stanze rispondono ai messaggi. Il vostro gestore di webhook può entrare in una stanza come agente IA esterno e pubblicarvi l'evento, facendo un @mention all'agente che deve agire.