Security of incoming webhooks

Keeping your endpoints secure is critical to protecting your customers’ information. Integrately provides two ways for you to verify that webhooks are actually coming from the app you connected in a secure manner.

You can secure your webhooks simply by using HTTPS scheme in webhook url. You can add additonal security by using Username & Password or by signing the payload with a Secret Key

  1. Username & Password: Select 'Username & Security' in Webhook Security field >Enter Username and Password you would like to use to secure your webhook.

    Usually, apps support adding Username and password while sending the webhook, you can add the same Username and Password you added in Integrately Webhook there.

    If the app does not support adding Username/Password, you can add Integrately webhook url by changing https://webhooks.integrately.com to https://{your_username}:{your_password}@@webhooks.integrately.com. However, you should not use this without HTTPS at the start of the webhook url.

    After configuring Username & Password security, if the received username and password do not match with what you have added, the webhook will be discarded.

  2. Secret Key: Select 'Secret Key' in Webhook Security field >Enter unique(different for every webhook you have) signing secret key to secure your webhook.

    A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, sender includes a timestamp in the IG-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature

    Sender generates the timestamp and signature each time an event is sent to Integrately. If sender retries an event (e.g., Integrately previously replied with a non-2xx status code under some circumstances), then a new signature and timestamp is generated for the new delivery attempt.

    Signature Format:The IG-Signature header included in each signed event contains a timestamp and one signatures. The timestamp is prefixed by ts=, and each signature is prefixed by v1 as shown in a sample signature below:

    IG-Signature: ts=1634617838,v1=c62af2e394ea77af961f8f4289dbaaa3d02e2883b445a393187c42389aa69c75

    Signature Generation:Integrately verifies signatures using a hash-based message authentication code (HMAC) with SHA-256

    Step 1: Get current timestamp in unix format for example: 1634617838, prefix it with ts=, so it becomes ts=1634617838

    Step 2: Create a string by concatinating timestamp, dot and actual payload or body of the event being sent. We call this string as "Signed_Payload"

    Step 3: Compute an HMAC with the SHA256 hash function. Use the webhooks’s signing secret(which you added in Webhook Security field in Integrately) as the key, and use the "Signed_Payload" string as the message. It will generate a code. Prefix this code with v1= to generate a string like v1=c62af2e394ea77af961f8f4289dbaaa3d02e2883b445a393187c42389aa69c75

    Step 4: Join outputs of Step1 and Step3 by a comma to create signature header value as given in the above example. Add IG-Signature header with value of the calculated signature to the request being sent to Integrately.

    Integrately calculates the signatures based-on received payload/request body using the signing secret specified in the webhook, if both the signatures are not same, the webhook will be discarded.

Troubleshooting

Troubleshooting of live automations can be done via History. The History section shows the API requests and responses for each step and operation.

To check the history or troubleshoot their integrations users can go to My Automations > Click on the flow which you wish to troubleshoot > History.

Contact Support

Support Team Hours - We provide 24/5 support to our users.

1st Response SLA - The maximum response time for any live support query is around a few minutes.

Link to create a support case - You can raise your request on the live chat on the website (https://integrately.com)

Link to email support - For email support please drop us an email on [email protected]

Link to your KB/Forums - You can check out our help docs from here https://integrately.com/docs