With webhooks, you can set up automated notifications and integrations, enabling seamless data transfer and immediate action based on specific events within the Flowcode platform.

Here are the steps to set up webhooks:

How to receive events —

Step 1:

Navigate to a Workspace and select the 'Manage' tab on the bottom left hand side navigation of your screen.

Step 2:

Select 'Webhooks' from the top navigation bar.

Step 3:

Minimum requirements

Our system requires that payloads are sent over a secure connection, so all endpoints must be https.

Receiving Flowcode events is as easy as creating an endpoint with at least one subscription to an event type from our catalog. The event catalog gives you a schema from which you can expect the webhook payload to reflect when subscribing to a given event type. Once in the webhooks tab of your Workspace management, click 'Add Endpoint'

Step 4:

In order to subscribe to events, simply check the ones that you are interested in, and whenever those events occur in the Flowcode system, they will be forwarded to your URL.

Advanced configuration

Rate limiting:

The rate limit is defined as the limit of the number of messages per second to send to the specified endpoint. This will help protect your servers from being overwhelmed in the event of a spike in messages*. It is an optional setting and if not specified, no rate limit will be applied. To apply a rate limit, click on the “Advanced” row below the “Message Filtering” options and you will be presented with rate limiting configuration options.

In the event a rate limit needs to be applied or adjusted, you can always edit the endpoint by clicking on it and navigating to the “Advanced” tab (see the “Custom Headers” section below to see the view).

Note 📝: If your rate limit is too low and are consistently receiving events above the limit, this may cause congestion in the system and we may ask that you increase the rate limit for your endpoint.

Custom headers:

Custom headers may be added to each of your webhook payloads for that endpoint after the endpoint has been created. Once your endpoint has been created, click on the endpoint from the endpoint list view, and you will see a section where you can add custom headers (and adjust your rate limit if needed). To add a new custom header, enter the header key and the header value, click the plus button and you’re done! Now on each webhook event you receive, those headers will show up configured with your values.

Additional auth requirements:

If your system requires additional means of authentication through headers, you can add these through the headers form. The “Authorization” header is treated as a special header and its value will be redacted from the UI and is non-revealable, so please be sure it is saved somewhere safe for future reference.

Webhook Verification —

It is always recommended to verify the sender of the webhooks before processing the payload. In order to verify that you are receiving events from Flowcode, you can examine the following headers upon receiving the payload:

webhook-id: the unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is being resent (e.g. due to a previous failure).
webhook-timestamp: timestamp in seconds since epoch.
webhook-signature: the Base64 encoded list of signatures (space delimited).

Locating your signing secret:

Each endpoint has its own webhook secret that they can use to verify that the payload is coming from the expected source.

You can view your webhook secret by clicking into the endpoint you’re interested in and viewing the secret as shown.

Rotating your signing secret

For your security, you may wish to rotate your signing secret. Please note that you will need to update your code to use the new secret when this action has been completed. To rotate your signing secret, click the dropdown arrow next to the secret’s label.

Note 📝: There will be a confirmation before your secret is rotated. Please read carefully before continuing.

Manually verifying the payload:

The content to sign is formatted in the following way (body being the raw body of the request):

JavaScript
signedContent = "${webhook_id}.${webhook_timestamp}.${body}"

In order to verify the payload, you will need to:

Create the signed content as demonstrated above.
Remove the whsec_ prefix from that secret that is used for your endpoint.
Base64 decode the remaining secret string.
Hash the signed content from step 1 (our webhooks system uses HMAC with SHA256).
The inbound webhook-signature header value will be a list of which you’ll want to take the first element and then remove the v1,prefix (i.e. the header may have a value that looks like v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= and all we care about in this case will be g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=)
Compare the result of this operation with the inbound webhook-signature header and if they match, the request has been verified.

With the below code, it accomplishes steps 1-4, and then after step 5 has been completed, the resulting values from each operation should match (step 6 AKA output from steps 1-4 must match the output from step 5) in order for the message to be verified as a legitimate Flowcode webhook event.

JavaScript
const crypto = require('crypto');

signedContent = `${webhook_id}.${webhook_timestamp}.${body}`
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";

// Need to base64 decode the secret
const secretBytes = new Buffer(secret.split('_')[1], "base64");
const signature = crypto
  .createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64');
// this signature should match our processed secret

If you keep getting errors, please ensure that your webhooks secret is correct for the intended endpoint and has not been rotated.

Manual alternatives:

If you would like to use something trusted and less tedious, this repository has SDKs for different languages that do a lot of this processing for you! For more documentation on using these libraries, you can see more information here.

Testing your Endpoint —

You can test your endpoint without triggering an event through flowcode using our event catalog examples. To do so, click on the endpoint you’d like to send test events to and navigate to the “Testing” tab.

Here, you can select an event type to send to your endpoint. Its body will consist of the values supplied in the corresponding example in the event catalog.

Retrying Events —

You may want to retry failed events in the event that your service has downtime or your endpoint was misconfigured.

Replaying single events:

If you only want to replay a single event, click into your endpoint where you are expecting that event, locate the event in the endpoint’s “Message Attempts” log, click into its actions menu and click “Replay.”

Recovering multiple failures:

If you need to recover multiple failed messages, you can do this by clicking into the endpoint, clicking on the actions menu, and clicking on “Recover Failed Messages.”

You can then select a time window from which to resend all failed messages.

Disabling or Deleting an Endpoint —

If you want to disable your endpoint for any reason, you can do so by clicking on the endpoint and selecting “Disable Endpoint” or “Delete” from the action menu.

Disabling vs. Deleting:

Both disabling and deleting an endpoint will stop any message attempts from occurring for that endpoint. The major difference is that a disabled endpoint can be re-enabled with the same configuration, whereas if an endpoint was deleted, its configuration and message attempts are gone. Please note that deleting an endpoint does not delete any messages from the message logs, only the message attempts that can be viewed directly from the endpoint view.

Retry Schedule —

In many webhook systems, retries are implemented with exponential backoff. The automatic retry schedule is:

Immediately
5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours (in addition to the previous)

This will give you time to troubleshoot and fix any issues with message consumption without creating a bottleneck in the system.

Any endpoint that is removed or disabled will automatically have its delivery attempts disabled as well.

If you have any questions, please don't hesitate to reach out to [email protected] — we'd be happy to assist you.