Come faccio autenticare i vostri callback presso il mio sistema?

Quando una firma si chiude facciamo una POST al tuo sistema (Come so quando qualcosa è finito?). Ogni callback è firmato con la nostra HMAC (X-Signer-Signature), così sai che è nostro. Ma molti sistemi vogliono anche che chi chiama si autentichi: un token OAuth, una chiave API, un token Bearer fisso. Salesforce Apex REST sul dominio della tua org è il caso più comune. Un ambiente dei callback è il modo in cui ce lo dai, una volta sola, nella console.

Configurarne uno

Nella console apri Environments nel menu a sinistra e aggiungine uno:

Campo	Che cos'è
Sigla	Un nome breve che una chiamata usa: lettere minuscole, cifre e `_`, al massimo 16, che comincia con una lettera. `prod`, `uat4`, `dev_5`. Non cambia mai.
URL base	https, eventualmente con un prefisso di percorso: `https://myorg.my.salesforce.com/services/apexrest`. Niente nome utente, niente query string. L'host deve essere un indirizzo pubblico: lo si controlla quando un callback viene inviato, e uno privato fa abbandonare il callback con il motivo nel registro dei Webhooks.
Autenticazione	Uno dei quattro tipi qui sotto, con le sue credenziali.

Tipo	Che cosa mandiamo
Nessuna autenticazione	Nient'altro che la nostra HMAC. Consentito, a tuo rischio: chiunque conosca l'URL può fare una POST, e verificare la firma diventa la tua unica prova. La console te lo segnala.
Token Bearer	`Authorization: Bearer <il tuo token>`
Chiave API in un'intestazione	`<l'intestazione che indichi>: <la tua chiave>`, per esempio `X-API-Key`
Credenziali client OAuth2	`Authorization: Bearer <access token>`, un token che prendiamo dal tuo URL del token con il tuo client id e secret (nel corpo del modulo o come HTTP Basic), con `scope`, `audience` e parametri di modulo aggiuntivi facoltativi

Il segreto (il token, la chiave o il client secret) è conservato cifrato e non viene più mostrato; per cambiarlo, scrivine uno nuovo. Il primo ambiente che aggiungi è quello predefinito. Aggiungerne un secondo non cambia mai il predefinito: lo cambi solo tu, con Make default.

Usarlo in una chiamata

Indica l'ambiente e manda solo la parte finale dell'URL. I percorsi sono accodati all'URL base:

"callbackUrl": {
  "env": "uat4",
  "onSuccess": "/doconure/ok",
  "onError": "/doconure/ko"
}

Lo stesso blocco funziona in POST /api/v1/sign/envelopes (in settings), in POST /api/v1/flow (in signature) e come webhook di completamento di un lavoro in blocco. Senza env, i percorsi vanno al tuo ambiente predefinito. Una chiamata che non manda alcun callback usa i percorsi predefiniti dell'ambiente predefinito (impostati nel modulo dell'ambiente, On success e On failure). Un URL completo https://... funziona ancora come sempre, senza ambiente e senza autenticazione.

Che cosa viene rifiutato, alla chiamata

Un env che non hai, oppure dei percorsi senza un ambiente predefinito: CALLBACK_ENVIRONMENT_UNKNOWN (1625). Un env che non è affatto una sigla valida (maiuscole, un trattino, più di 16 caratteri) è rifiutato dalla forma della richiesta, INVALID_REQUEST_BODY (1101), e così un URL il cui schema non è né http né https. Un URL http:// è accettato alla chiamata ma non viene mai chiamato: un callback va solo in https, quindi usa https.
Un percorso che potrebbe cambiare l'host (uno schema, //, @, .., una barra rovesciata, un #), un URL completo insieme a env, oppure un percorso mescolato a un URL completo: CALLBACK_PATH_INVALID (1626). È questo che fa andare le tue credenziali solo al tuo host.

Entrambi sono rifiutati prima di creare o addebitare qualsiasi cosa: lo scopri alla chiamata, non due giorni dopo nel registro delle consegne. Nella chiamata non c'è un tipo: il tipo di autenticazione appartiene all'ambiente.

Quali sigle posso mandare?

Chiedilo prima di essere rifiutato: GET /api/v1/callback-environments elenca gli ambienti della tua organizzazione, il predefinito per primo, leggibile da qualsiasi chiave attiva.

{ "environments": [
    { "env": "uat4", "isDefault": true, "authType": "bearer",
      "defaultSuccessPath": "/doconure/ok", "defaultErrorPath": "/doconure/ko" },
    { "env": "prod", "isDefault": false, "authType": "oauth2_client_credentials",
      "defaultSuccessPath": null, "defaultErrorPath": null } ],
  "count": 2 }

Sola lettura, e non dice nulla da cui possa trapelare una credenziale: niente host, niente nome di intestazione, niente token o client secret, solo la sigla, quale è il predefinito, il tipo di autenticazione e i percorsi predefiniti. Creare o modificare un ambiente resta nella console. Per essere avvisato quando un firmatario è sostituito, aggiungi onEvent accanto agli altri due percorsi (vedi Essere avvisati quando un firmatario è sostituito).

Come viene consegnato un callback

L'ambiente si legge quando il callback viene inviato, quindi cambiarne l'URL base o ruotarne il segreto vale anche per i callback già in attesa.
Un token OAuth2 si prende la prima volta che serve, si tiene finché scade, e si riprende una volta se il tuo sistema risponde 401. Un endpoint del token fermo o che risponde un errore viene ritentato con la cadenza ordinaria; il tuo sistema non viene mai chiamato senza un token.
L'URL del token segue le stesse regole del callback: solo https, solo indirizzi pubblici, redirect mai seguiti. Un URL del token su un indirizzo privato fa abbandonare il callback (è la tua configurazione da correggere, non qualcosa che si sistema col tempo).
I percorsi predefiniti di successo e di errore appartengono all'ambiente predefinito. Senza un ambiente predefinito non ci sono percorsi predefiniti, e una chiamata che manda solo un percorso è rifiutata con 1625.
La nostra HMAC e le intestazioni X-Signer-* viaggiano con ogni callback, più X-Signer-Environment con la sigla.
Un ambiente ancora indicato da buste aperte, lotti in corso o callback in attesa non si può eliminare (CALLBACK_ENVIRONMENT_IN_USE).

La pagina Webhooks mostra ogni consegna con il suo ambiente, e può mandare un evento di esempio attraverso uno di essi, così verifichi l'autenticazione prima che si chiuda una busta vera.

Salesforce, come esempio

Nella tua org crea una External Client App (o una connected app) con il flusso client credentials attivo e un utente run-as, ed esponi una classe Apex REST, per esempio, su /doconure/ok. Poi aggiungi un ambiente:

Sigla           prod
Base URL        https://myorg.my.salesforce.com/services/apexrest
Authentication  OAuth2 client credentials
Token URL       https://myorg.my.salesforce.com/services/oauth2/token
Client id       (the consumer key)
Secret          (the consumer secret)

e manda "callbackUrl": {"onSuccess": "/doconure/ok", "onError": "/doconure/ko"}. Nessun Site, nessun utente ospite, nessun intermediario. I dettagli dell'app dipendono dalla versione e dalle impostazioni della tua org: verificali nella configurazione di Salesforce.

Il corpo del callback e la sua firma: Come so quando qualcosa è finito? · Salesforce (Apex)