About converting targets to webhooks
Consider the following before converting your targets.
- The conversion tool only converts HTTP targets.
- Targets must be active to be converted. Disabled and deactivated targets won’t be converted.
- Webhooks don’t support HTTP authentication. Any targets that use authentication must be updated to use HTTPS before you can convert them.
- All eligible targets will be converted. It isn’t possible to convert one target at a time.
- Targets will remain active until they’ve been successfully converted or until HTTP targets are deprecated.
- If any part of the conversion fails, everything related to the target(s) that failed is rolled back. In no circumstances should a failed conversion affect existing configurations of triggers and business rules.
- The conversion is fully reversible until HTTP targets are deprecated. If, for any reason, you want to revert a target you converted, you can do so.
Preparing HTTP targets to be converted
There are two scenarios in which targets cannot be converted:
- Targets use HTTP instead of HTTPS and have basic authentication enabled
- Targets are inactive
In most cases, there are simple ways to modify the targets so that they can be included in the conversion.
Changing from HTTP to HTTPS
During the conversion process, you can choose to Convert unsecure targets to secure webhooks (HTTPS) or skip them. If you choose to convert insecure targets, no action is required to resolve this ahead of time.
If you wish to convert only some of your HTTP targets that use HTTP, you can manually update the URLs for just those targets and then select Don’t convert unsecure targets during the conversion process.
To change a target URL from HTTP to HTTPS
- In Admin Center, click the Apps and integrations icon (
) in the sidebar, then select Targets > Targets.
- Find the target in the list and click Edit.
- Update the Url value to use https.
- Select Update target from the drop-down and click Submit.
Making sure targets are active
Only active HTTP targets are eligible for conversion.
To activate a target
- In Admin Center, click the Apps and integrations icon (
) in the sidebar, then select Targets > Targets.
- Find the target you want to reactivate inn the Inactive targets list and click activate.
Converting HTTP targets to webhooks in Admin Center
The conversion process starts by cloning all existing targets. The business rules are then modified to use webhooks instead of targets. The final step is deactivating the targets and activating the webhooks.
If the conversion is successful, the HTTP targets are deactivated, the webhooks are activated, and the business rules are updated almost simultaneously.
If the conversion of a target failed, the target and corresponding triggers will remain active and unchanged.
To convert HTTP targets to webhooks
- In Admin Center, click the Apps and integrations icon (
) in the sidebar, then select Webhooks > Webhooks.
- Click Get Started.
If you have targets that are eligible for conversion, you’ll be guided through the conversion process.
- Click Manage targets to ensure your targets are prepared for the conversion and then click Next.
- Review the summary of eligible targets and click Convert targets.
- If insecure (HTTP) targets are detected, you can choose to Convert unsecure targets to secure webhooks (HTTPS) or Don’t convert unsecure targets.
Note: Converting insecure targets to secure webhooks could break your workflows if your server doesn’t support HTTPS.
- Click View targets conversion log to see which targets were successfully converted as well as any that failed.
Targets skipped during conversion
Viewing the conversion log
At the end of the conversion process, there’s a prompt to view the conversion log. You can also access it at any time from the Webhooks page. To view the conversion log, click Actions at the top of the page and then click View targets conversion log.
- The Converting tab is only populated during the conversion process. It should be empty most of the time.
- The Converted tab shows a record of all webhooks that were successfully converted. From this tab you can view a webhook in more detail, revert a webhook back to a target, and find the conversion ID for a given webhook.
- The Failed to convert tab shows a record of each eligible target that didn’t convert successfully. Use this tab to see the details about why the conversion failed and retry the conversion for each target.
Retrying a conversion
From the Conversion Log, you can see which targets failed to convert and retry the conversion.
To retry the conversion of a target
- In Admin Center, click the Apps and integrations icon (
) in the sidebar, then select Webhooks > Webhooks.
- Click Actions at the top of the page and then click View targets conversion log.
- Click the Failed to convert tab, and find the target you want to retry.
- Resolve the error described for the target.
- Click the options icon (
) on the target's row and click Retry conversion.
While the conversion is retried, the target will be listed on the Converting tab. When the conversion retry is complete, the target will either be moved to the Converted tab or the information about the target’s failed conversion will be updated on the Failed to convert tab and the target will be moved to the top of the table.
Resolving conversion errors
Failure | Reason | Fix |
---|---|---|
Failed to update trigger | The update to the trigger that is calling the webhook failed. This if often caused by an invalid trigger configuration, unrelated to the conversion. | Review your triggers to ensure they can be modified and saved, then try the conversion again. |
Failed to update target | The update to disable the HTTP target failed. This is typically caused by an invalid target configuration, such as an invalid target URL. | Review your HTTP targets and ensure that the targets can be modified and saved, then try the conversion again. |
Failed to update webhook | The webhook wasn't created because of validation issues. | Review your HTTP targets to ensure they are properly prepared to be converted, then try the conversion again. |
Reverting a converted webhook back to a target
To revert a webhook to a target
- In Admin Center, click the Apps and integrations icon (
) in the sidebar, then select Webhooks > Webhooks.
- Click Actions at the top of the page and then click View targets conversion log.
- Click the Converted tab, and find the target you want to revert to a target.
- Click the action menu icon (
) and click Revert to target.
After the webhook is successfully reverted to a target, it's removed from the list on the Converted tab.
115 Comments
Thanks @...
I will share details in the ticket.
Is it just me, or does anyone else think it's weird having this situated in the Admin section?
So now when I'm building something and need a webhook, I'm going to have to enter the Admin part, which I really only use to allow Zendesk Assumption.
Was there some logic for removing it from the normal working area where I make changes?
Does this impact links that are added in Knowledge Base articles?
Thanks,
Laura M
We have integrated targets into our GitHub/Azure DevOps ticket integration app Git-Zen; the targets are installed via the requirements.json so that they won't be inadvertently altered. However, there does not seem to be an allocation for webhooks in the requirements.json:
https://developer.zendesk.com/documentation/apps/app-developer-guide/apps_requirements/
What is the plan with regard to being able to include webhooks within the app requirements, as is currently done with http_targets?
@...
Good question. In the coming months you'll be seeing more settings move to Admin Centre. The reason for this is because Zendesk is more than just ticketing, and webhooks will be extended to cover multiple products (not just Support), so Admin Centre is where this lives to control webhooks across multiple products.
@...
This only affects targets, it should not affect any links present on a knowledge base.
@...
This is coming soon, we do plan to have webhooks available in apps requirements to allow partners to take advantage of it. We are also working on the plan for getting requirement-created targets over as well. Stay tuned.
Hi Chris,
We just converted ours to webhooks and are running into the same issue as Walter.
No JSON payload is being sent to our endpoint with the webhook. The trigger is configured with a JSON body:
@...
That makes sense overall thanks.
Can I suggest then that where the extensions part is in support, we have a jumplink to webhooks so we can find it easily?
Hi @...
I think it would be worthwile to revise and cross link the articles regarding replacement of http targets with webhooks, and to concentrate comments in one (this?) article only.
From what I read up to now, current state of affairs is:
If your targets are not converted at this time, this might be the problem
Yours truly
Peter
(Updated with Chris' information)
Hi @...
Thank you for the feedback. We'll look into making a quick link from the Targets page to Webhooks.
Hi @...
Thanks, that's a great breakdown. Comment bodies were fixed a couple of days ago, but the rest is looking good. I'll add this to our article here.
Chris
As far as I'm concerned, the issue regarding the migration of existing http target has been fixed.
Thanks!
@...
you are saying comment bodies are fixed?
I don't think so, look at my comment in this conversation 3 days ago, I jsut tested now and comment body is still returning in string in API, which makes JSON mis-format.
thanks.
I tried to convert one target, but the target failed. I went back through the process and clicked 'Convert Targets' but I keep getting an error that there are no targets to convert.
@... Yes, I can confirm the initial issue with comment bodies with new lines has been fixed. I'll open a ticket on your behalf and we can take a look.
@... I took a look at the target, and it appears the trigger that your target is currently attached to it invalid. I'd recommend taking a look at the trigger specifically, fixing up any issues and re-trying :)
I tested it in the sandbox and the webhook works fine, but the trigger that sent the webhook is not logged in the event. Is this an error?
Hi @...,
I am also having the same issue after converting our targets. I am getting an empty payload error when sending a test.
I would love to hear what the fix was for @...
Thanks,
Aaron
When will placeholders be supported by webhooks?
My targets are created by survey app and therefore I cannot edit them. Will they be updated automatically?
Hi @...,
You can check on the triggers currently using that webhook by going to the webhook details and viewing the "Event Subscription" tab. We're currently working on improving the ticket events trigger message as well.
Hi @...,
Thanks for the report. I'll generate a ticket on your behalf and add you to ensure you're notified of the fix. We are aware of an issue with some servers not supporting `chunked` transfer encoding. We are making changes to bring this back to the same as targets with a standard `content-length` header instead.
Hi @...,
We are aiming to release support for placeholders in URLs in the next few weeks. I will update this thread once that's out.
Hi @...,
This is expected. We will be working with app partners on migrating those targets to webhooks separately. There is no action for you for those targets.
Hi @...
We use placeholders in majority of our targets so we are keen to hear when conversion of these targets will be supported.
How can we subscribe for updates on this subject? Will the update be via a comment here or there will be an email notification sent as an announcement?
Thanks
Hi @...,
Placeholders are available to be used now in webhooks for payload bodies. In URLs, this is coming very soon. When it's out, I'll post a comment here and documentation will be updated.
Chris
Hi everyone, just to update we have resolved the issue some people were experiencing with blank payloads being sent.
Chris
Hi @... -
Thanks for your continued updates to this thread - it is great to see active engagement, especially for something as important as this!
Has there been any movement with regard to including this within developer options? Especially considering the lead time required for Marketplace app approvals, etc, this is important to nail down. To recap: there does not seem to be an allocation for webhooks in the requirements.json:
https://developer.zendesk.com/documentation/apps/app-developer-guide/apps_requirements/
What is the plan with regard to being able to include webhooks within the app requirements, as is currently done with http_targets?
Thank you!
Hello everyone,
I'm pleased to report that placeholders in URLs for webhooks is now live. You can create new webhooks with placeholders in the URL and have them work as they did with targets.
Note, targets using placeholder URLs are not yet eligible for conversion using our conversion tool just yet. We hope to enable them next week.
We appreciate everyone's patience on this!
Chris
Hey @...,
Thanks for the comment. Our plan is to have webhooks available inside of app requirements, as well as a transition for existing target requirements to webhooks with minimal to no admin or developer action required.
Unfortunately, I can't give a more specific time-frame but we have absolutely committed to doing this before the deadline. We will not be shutting anything off if people have not had any opportunity to migrate.
We'll update once we have a clearer idea of our path forward, so really appreciate you hanging in there!
Chris
When can we expect the support for API-Key header or custom header in the Web Hook?
Hi Chris Sos, we still cannot see an option to convert targets in the Admin Center, although all our Targets are httpS and active.
We see only "Create webhook" option available.
Hi Dmitry,
In Admin Centre on the webhooks page, from the actions menu you should see "Convert targets" in the dropdown, this should allow you to view convertable targets and perform the conversion:
Are you saying you're not seeing this option at all? Or when on the page you're not seeing any targets available to convert?
Chris
Chris - I'm in the same position as Dmitry. On the webhooks page, this is all I see (there is no Actions menu):
For users accessing "Webhooks" page for the first time, that menu doesn't exit, and then need to try creating a new webhook and cancel it.
It would be great if you could fix that UX issue so the dropdown menu will appear in the first place on Webhook page.
Hey @...,
Thanks for the extra detail! Yeah I can see that being confusing if you're coming straight to the webhooks page. I've made a note of that and will bring it up with our UX team.
Glad you're able to convert :)
Chris
Please sign in to leave a comment.