Webhooks provide the ability to notify a third party application of changes that are made within Go Method. Within Go Method, multiple webhooks can be created to track how data is moved. Webhook invocations will be tracked per Webhook that pushes data.
In order to setup webhooks, a Go Method user must have the 'Developers' permission. Even System Admins will not have the developers menu, the 'Developers' permission will need to be added to an existing role or a new role with the 'Developers' permission will need to be created. In order to get to the permission, go to Admin < Manage Admins < Roles and either select an existing role or create a new role. The permission to look for is illustrated below.
Once the permission is assigned to the role, anyone with that role will see a new top menu.
Creating a webhook
To create a new webook, click 'Developers' from the top menu, then click 'Webhooks' from the side menu. Then click 'New Webhook'
Creating a new webhook will require filling out the required fields to describe the need for the webhook.
- Webhook Event: This is the type of event that will trigger the webhook.
- Individual Profile: When data about an individual profile is either created or updated.
- Participant: When data about the participant is either created or updated.
- Webhook Name: Choose a name that will reflect the reason for creating the webhook.
- Endpoint Url: This is the url that you would like the webhook to push to. This will usually be a url hosted by your organization.
- Max Retries: The number of times the webhook will attempt to push data to the endpoint url. It will be retried in the event of a failure.
- Webhook Triggers: Specify what will trigger the webhook. Its possible to only trigger on a create or an update or both can be selected.
Viewing and Managing Webhooks
Once the webhook is created, it is possible to view the webhook invocations that have happened. To view the invocations for a webhook, navigate to Developers < Webhooks and then click on the webhook to view.
When viewing a webhook, there are a couple points of interest.
- Signature Secret: Each webhook that is sent will have a header called 'FullMethod-Signature'. This is an optional way to validate that the request that is being sent to the endpoint url is valid and sent from Go Method.
- 'Run Test': Clicking this button will send a webhook with a payload to the endpoint url. The data within the payload will not be valid, it is only to test that the endpoint url is receiving data the way it's intended.
- Invocations: This will show a list of the invocations that have happened within the last 7 days. It will display the body of the request that the webhook sent to the endpoint url along with the response that was received back from the endpoint url.
The webhook payload is a json object that captures the records that triggered the webhook
- recordId: The id of the record that triggered the webhook invocation. For individual this is the 'personid', for participant this will be 'participantId'
- changeType: The type of change that happened that triggered the webhook. The available options will be 'CREATE' and 'UPDATE'
- webhookEvent: This is the event for the webhook, the options are INDIVIDUAL_PROFILE or PARTICIPANT_PROFILE
For security purpose, the only data that is sent is the record ID. In order to get the details about the record, a call from the Graph API will need to happen based on the record id. For INDIVIDUAL_PROFILE, the graph query will be on person(), for PARTICIPANT_PROFILE the graph query will be participant()
All webhook requests come with a signature in the fullmethod-signature header. This is a way to verify that the webhook request came from Go Method. You can perform a verification by providing the event payload, the fullmethod-signature header and the endpoint's signature secret.
Go Method requires the raw body of the request to perform the signature verification. If you are using a framework that formats the json payload, make sure when performing the signature that it is off the raw body.
The fullmethod-signature header included in each webhook event contains a timestamp and one signature. The timestamp is prefixed by t=, and the signature is prefixed by a signature. An example would be
Step 1: Get the timestamp and the signature
First split the header using the ',' character as the separator in order to get the list of elements. (t and signature). Then split each element using the '=' as the separator. The value for the prefix 't' is the timestamp of the request and 'signature' is the actual signature for the request.
Step 2: Create the signed payload
The signed payload string is created by concatenating the timestamp followed by a '.' and then the actual raw JSON payload.
Step 3: Create the expected signature
Compute an HMAC with the SHA256 hash function. Use the webhook signature key as the key, and use the signed payload string (example above) as the message.
Step 4: Compare the signatures
Compare the signature that you created with the signature from the fullmethod-signature header. Also, use a current timestamp against the timestamp in the signature header to determine if the difference between the timestamps is ok with you.