Webhooks migration guide for complex scenarios

Learn about the additional impact of transitioning to our new service based on your specific setup

Should I migrate to the new service and endpoints?

If you are considering using Codat's new webhook management endpoints, check that your setup is compatible first. Find the scenarios applicable to your existing setup and see if you can migrate.

I am using...	Action and impact
...email notification functionality	- Migrate to the new webhook service - Review the critical considerations
...event log endpoints (e.g. /rules/alerts)	- Do not migrate until you have removed all calls to logs endpoints from your application logic - Review the critical considerations
...RuleId in my application's existing logic	- Do not migrate until you have removed all application logic using the RuleId property - Review the critical considerations
...only company-agnostic webhook functionality	- Request to migrate to the new webhook service
...company-specific webhook functionality	- Request to migrate to the new webhook service - Review the additional considerations
...X-Codat-ClientId header to determine the source Codat instance of the event	- Request to migrate to the new webhook service - Review the additional considerations
...webhook auth header via the /profile endpoint	- Request to migrate to the new webhook service - Review the additional considerations
...webhook auth header via the Portal	- Request to migrate to the new webhook service - Review the additional considerations
...Retry-After header to control the time between retries	- Request to migrate to the new webhook service - Review the additional considerations

Critical considerations

Event log endpoints

Our new service has a robust retry policy that ensures we attempt to deliver an event multiple times over a 28-hour period. This means you don't need to write any complex logic to manage undelivered events. As a result, you no longer need to use any of these endpoints:

• GET /rules/alerts
• GET /rules/{ruleId}/alerts
• GET /rules/alerts/{alertId}

Check out the deprecation notice for full details of these changes.

Email notification functionality

Our new webhooks service supports sending notifications for events using our Zapier app, so you can build automated workflows to send email, Slack, or other notifications. Use our webhook events as triggers and drive actions in all of the tools you use, from Google Sheets to SalesForce.

For detailed instructions on creating automated notifications with Zapier, see our Zapier guide.

RuleId in existing logic

If you are using RuleId properties returned by our existing webhooks in your application logic, review and update your application logic to remove any dependencies on the RuleId. This will help prevent any disruptions to your integration with Codat.

You should use RuleType to identify what event a given webhook corresponds with.

Check out the deprecation notice for full details of these changes.

Additional considerations

Depending on your setup, you may need to configure your webhook consumers in Codat further or be aware of changes to the UI.

IP allowlist

If your consumer endpoint is behind a firewall or NAT, make sure to allow messages from 4.159.114.108 and 20.117.190.191.

Source client header

If you are using multiple Codat instances and need to differentiate between them, you can filter the messages by client using a custom X-Codat-ClientId header.

If you are already using this header in your existing setup, we will include it when migrating your rules to the new service. For more information on creating custom headers in webhook consumers, see Custom headers.

Webhook auth header

If you are currently securing your webhook endpoints with an authorization header, you can add it as a custom Authorization header to the webhook consumer endpoint using our Portal. It is no longer possible to do this via our API.

If you are already using this header in your existing setup, we will include it when migrating your rules to the new service. For more information on creating custom headers in webhook consumers, see Custom headers.

Retry-After header

Our new service has a robust retry policy that ensures we attempt to deliver an event multiple times over a 28-hour period. As a result, you no longer need to set a Retry-After header to control the time between retries.

Company-specific webhooks

For scalability, we limit the number of webhook consumers to 50. This means there are new considerations for handling company-specific webhooks.

The updated webhook service now supports passing metadata about a company and filtering companies using company tags.

Passing metadata to a webhook consumer

You can now pass metadata about a company by setting tags on your companies.

For example, if you previously passed metadata via the webhook consumer's path, such as:

POST /region/{regionId}/accounts/{accountId}

You will now set this information when creating or updating a company:

{
    "name": "{you company name}",
    "tags": {
        "region": "{regionId}",
        "account": "{accountId}",
    }
}

This metadata will then be passed to your webhook consumer in the payload.referenceCompany.tags property.

For more details, read our guide on adding metadata to a company.

Filter webhooks by company tags

To route specific companies to designated webhook consumers, use the company tags filter for your webhook consumer.

This feature allows you to send messages only for companies with tags that match any of the tags defined on the webhook consumer.

For additional information, read about filtering webhooks by company tags.

---

Read next

• Event types
• Configure webhook consumers
• Troubleshooting