DocuSign RecipientId changed by DocuSign - Effective way for mapping recipients in webhook responses?

Question

When using the DocuSign REST API, I assign a numeric value to each recipient in my envelope, starting from 1, 2, 3 etc.

However, when I receive DocuSign webhook events, within the RecipientStatuses section in the DS payload, the 'RecipientId' is now a GUID (generated by DocuSign). This Id means nothing to me, and so I can't use my originally assigned Recipient Id to map from the DS response to the relevant recipient in my system.

I'm not sure I can rely 100% on Name & Email for the mapping.

So, I thought I'd make use of the 'CustomFields' section against each recipient, as that seems comes back in the webhook payload unchanged. However, I've done some more testing and found a scenario where this logic falls down.

If my recipient happens to reassign to another user (upon visiting the signing ceremony), whilst I do receive a webhook event containing the updated RecipientStatuses (which now shows the original recipient as 'Completed' and a NEW recipient - the one that it was reassigned TO), the custom field that I'd assigned is moved out from my original recipient and into the NEW recipient - so if I was to use that custom field value as my approach to mapping, I would now have a recipient in my system with that custom field value that does not correspond with the recipient sent in the webhook payload.

I would use the list envelope recipients method to determine the mappings from my RecipientId to DocuSigns auto generated (Guid) RecipientId, but with the API limits, I can't make that call every time I receive a webhook event to get the latest recipient mapping data.

Has anyone come up against this issue, or implemented an alternative solution for this?

Answer 1

Good question. For now, I'd suggest that you record the triplet of {name, email, guid} where guid is a unique guid value that you assign to a recipient customField (as you're doing now).

This should then let you keep track of the recipients, including detecting the case of a recipient forwarding to another person that you discuss in your question.

But I also am puzzled by your statement that the {name, email} pair are not enough for identifying a given recipient. As it happens, DocuSign itself assumes {name, email} is a unique pair per person for various flows in the system.

Lastly, remember to test the case where the recipient changes their name. This can be done when a signing recipient first "adopts" a signature. Eg, they might change their name from an initial "Bob Smith" to their legal name of "Robert Smith" in preparation for signing your document.

Re: API limits -- as long as you're using Connect webhooks (and not polling), upgrading your API limit is usually not too hard. Discuss with your DocuSign customer support contacts or account manager.