Come faccio autenticare i vostri callback presso il mio sistema?
Quando una firma si chiude facciamo una POST al vostro sistema (Come so
quando qualcosa è finito?). Ogni callback è firmato con la nostra HMAC
(X-Signer-Signature), così sapete 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 vostra org è il caso più comune. Un ambiente dei
callback è il modo in cui ce lo date, una volta sola, nella console.
Configurarne uno
Nella console aprite Environments nel menu a sinistra e aggiungetene 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 vostro rischio: chiunque conosca l'URL può fare una POST, e verificare la firma diventa la vostra unica prova. La console ve lo segnala. |
| Token Bearer | Authorization: Bearer <il vostro token> |
| Chiave API in un'intestazione | <l'intestazione che indicate>: <la vostra chiave>, per esempio X-API-Key |
| Credenziali client OAuth2 | Authorization: Bearer <access token>, un token che prendiamo dal vostro URL del token con il vostro 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, scrivetene uno nuovo. Il primo ambiente che aggiungete è quello predefinito. Aggiungerne un secondo non cambia mai il predefinito: lo cambiate solo voi, con Make default.
Usarlo in una chiamata
Indicate l'ambiente e mandate 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 job massivo. Senza env, i percorsi vanno al vostro 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
envche non avete, oppure dei percorsi senza un ambiente predefinito:CALLBACK_ENVIRONMENT_UNKNOWN(1625). Unenvche 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 URLhttp://è 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 aenv, oppure un percorso mescolato a un URL completo:CALLBACK_PATH_INVALID(1626). È questo che fa andare le vostre credenziali solo al vostro host.
Entrambi sono rifiutati prima di creare o addebitare qualsiasi cosa: lo scoprite 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?
Chiedetelo prima di essere rifiutato: GET /api/v1/callback-environments elenca gli
ambienti della vostra 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, aggiungete 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 vostro sistema risponde
401. Un endpoint del token fermo o che risponde un errore viene ritentato con la cadenza ordinaria; il vostro 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 vostra 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-Environmentcon la sigla. - Un ambiente ancora indicato da buste aperte, batch 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ì verificate l'autenticazione prima che si chiuda una busta vera.
Salesforce, come esempio
Nella vostra 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 aggiungete 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 vostra org: verificateli nella configurazione di Salesforce.
Il corpo del callback e la sua firma: Come so quando qualcosa è finito? · Salesforce (Apex)