Our new webhook support provides another powerful way to interact with our services.<\/h2>\n\n\n\n\n\n<\/p>\n\n\n\n![\"Raymond](\"https:\/\/miro.medium.com\/v2\/resize:fill:88:88\/1*ldF-FsLonNyTUOmQ7cIV_g.jpeg\")
<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/a><\/p>\n\n\n\n\n![\"Adobe](\"https:\/\/miro.medium.com\/v2\/resize:fill:48:48\/1*riyFijvwTfGcWNf1guRNtg.png\")
<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/a><\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n\n\n![\"\"]()
<\/picture><\/div>\n<\/div>\n<\/figure>\nThis week the Acrobat Services team launched new support for webhooks with our APIs.<\/p>\n
In this post, I\u2019ll demonstrate how they work and what they provide to developers. Before getting into the details, some notes.<\/p>\n
First off, this new feature is only<\/em> available to folks using the Java SDK (updated this week to version 4) or the REST API directly. I\u2019m a Node.js developer and prefer the REST API over the SDK anyway, so the examples provided here will be Node.js-based.<\/p>\nSecondly, this feature only works with \u201cinternal\u201d files, or assets you upload to Adobe for processing. It isn\u2019t yet supported with cloud storage providers.<\/p>\n
Lastly, while this new feature is supported in all the various APIs within Acrobat Services, currently PDF Properties is not<\/em> supported. It will be at a later time.<\/p>\nAt a basic level, a webhook is a way for a service to let your code know something has happened. To be clear, it\u2019s to let your code, not you specifically, know something that has happened.<\/p>\n
For example, I can set up a webhook in GitHub so that when a person files a new issue, GitHub will make an HTTP request to a URL I specify. In order for that to work, I need a server of some sort that can listen to that and respond to the webhook.<\/p>\n
In some ways, it\u2019s the opposite of an API call. Instead of my code hitting the API to do something, the service itself calls my code to do something.<\/p>\n
Webhooks can be especially useful for cases where operations take \u201csome time\u201d. I put that in quotes to cover the widest range of possible versions of that. Most Acrobat Services operate in seconds, but as it\u2019s not instantaneous, it does take \u201csome time.\u201d You can imagine other APIs, perhaps involving video production, where \u201csome time\u201d could instead be minutes of time, or even hours.<\/p>\n
With situations like this, a webhook is useful as it lets my code start the \u201cslow\u201d process and the webhook can let me know when things are done. That\u2019s exactly<\/em> how the webhook feature of Acrobat Services will help developers!<\/p>\nNow let\u2019s take a look at how to use this new feature.<\/p>\n
All of the supported APIs follow a similar format. After you\u2019ve uploaded your asset, you then create a job with any required and optional arguments. Consider the Create PDF operation<\/a>. When making the REST call, the body can be as simple as this:<\/p>\nTo specify a webhook, you add a new property to your request body, notifiers<\/code>. notifiers<\/code> is an array of objects that take this shape:<\/p>\nFor now, don\u2019t worry about headers<\/code> or type<\/code> (type<\/code> will always be ‘CALLBACK’), but note the url<\/code> property. This is the URL that you’re asking Acrobat Services to request when the process is done. At minimum, a Create PDF body with a webhook would look like so:<\/p>\nThis means:<\/p>\n
Here\u2019s an example of a function that takes an asset and webhook (along with credential information) and kicks off a Create PDF job:<\/p>\n
I\u2019ll share complete examples of my demos at the end of this article.<\/p>\n
Now that you\u2019ve seen how to specify a webhook when creating jobs, how do you actually work with them?<\/p>\n
That\u2019s something I can\u2019t really answer here as it\u2019s going to depend on your own architecture and setup. To be clear, you need something<\/em>, whether it\u2019s a web server or a serverless endpoint, that can respond to the webhook call.<\/p>\nThere\u2019s a near infinite list of ways that you can do that, but for today, I\u2019ll share an incredibly simple Node.js script that when run, and exposed publicly, will listen and report on requests. My thanks go to Todd Sharp<\/a> for helping me with this.<\/p>\nHere\u2019s the entire server:<\/p>\n
When run from the command line, it will listen on port 3000 and on every request, dump out to the console and body and headers. Finally, it always returns this JSON body:<\/p>\n
This is required<\/strong> for your webhook so however you build it, ensure you return this response!<\/p>\nAs mentioned in the comments, one way this script could be exposed publicly is via ngrok, so after running that, you can take the resulting URL and use that as your webhook.<\/p>\n
Once used in a job, the webhook will be called when the job is done, and you can see an example request body below:<\/p>\n
Now, looking at this, you may wonder \u2014 how do I associate the data in this request to my original job? You can see the jobID<\/code> value there and it will match a portion of the URL returned from the job creation. If you remember, the job is created by the API call and returned in the Location<\/code> header.<\/p>\nIn my last test, it looked like so:<\/p>\n
https:\/\/pdf-services-ue1.adobe.io\/operation\/createpdf\/FAQjIUIGfuIkgcBMMunRsZ56P6qoQ4bR\/status<\/a><\/p>\nYou can see the jobID<\/code> in the data sent to the webhook matches the string before status<\/code> in the URL above. A bit of string parsing would make it possible to connect the two, but you must handle this yourself<\/em>. Since it’s asynchronous, you’ll need to store the job ID in a database or other persistence system.<\/p>\nAnother option is the use of custom headers. Remember back when I showed you the \u2018shape\u2019 of a request that includes webhooks, it looked like so:<\/p>\n
The headers<\/code> value is optional and can be any number of name and values. So for example:<\/p>\nWhen Acrobat Services completes work on your job and hits your webhook, it will pass those values as custom HTTP headers. You can then check for them in your code.<\/p>\n
Here\u2019s a modified version of the function shown earlier that includes a header based on the current date. This probably wouldn\u2019t be useful, but gives you an idea how it looks.<\/p>\n
If you remember, or server code dumps out headers too. When using the version above, here\u2019s what you can see when the webhook is executed.<\/p>\n
You can see the custom cats<\/code> header along with the usual headers sent in a request. Again, the validation, connection, etc. between the initial request and the webhook call is up to you, but you’ve got options for how you handle that. (As a quick aside, note you can also write webhooks using PowerAutomate. I’ll have a demo of this in the future.)<\/p>\nTo get started testing this new feature out, sign up for your free credentials<\/a> today and hit up our support forums<\/a> if you\u2019ve got any questions. You can find the complete source code for the demos in this post here: https:\/\/github.com\/cfjedimaster\/document-services-demos\/tree\/main\/webhooks<\/a><\/p>\n<\/div>\n
<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/a><\/p>\n <\/a><\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n This week the Acrobat Services team launched new support for webhooks with our APIs.<\/p>\n In this post, I\u2019ll demonstrate how they work and what they provide to developers. Before getting into the details, some notes.<\/p>\n First off, this new feature is only<\/em> available to folks using the Java SDK (updated this week to version 4) or the REST API directly. I\u2019m a Node.js developer and prefer the REST API over the SDK anyway, so the examples provided here will be Node.js-based.<\/p>\n Secondly, this feature only works with \u201cinternal\u201d files, or assets you upload to Adobe for processing. It isn\u2019t yet supported with cloud storage providers.<\/p>\n Lastly, while this new feature is supported in all the various APIs within Acrobat Services, currently PDF Properties is not<\/em> supported. It will be at a later time.<\/p>\n At a basic level, a webhook is a way for a service to let your code know something has happened. To be clear, it\u2019s to let your code, not you specifically, know something that has happened.<\/p>\n For example, I can set up a webhook in GitHub so that when a person files a new issue, GitHub will make an HTTP request to a URL I specify. In order for that to work, I need a server of some sort that can listen to that and respond to the webhook.<\/p>\n In some ways, it\u2019s the opposite of an API call. Instead of my code hitting the API to do something, the service itself calls my code to do something.<\/p>\n Webhooks can be especially useful for cases where operations take \u201csome time\u201d. I put that in quotes to cover the widest range of possible versions of that. Most Acrobat Services operate in seconds, but as it\u2019s not instantaneous, it does take \u201csome time.\u201d You can imagine other APIs, perhaps involving video production, where \u201csome time\u201d could instead be minutes of time, or even hours.<\/p>\n With situations like this, a webhook is useful as it lets my code start the \u201cslow\u201d process and the webhook can let me know when things are done. That\u2019s exactly<\/em> how the webhook feature of Acrobat Services will help developers!<\/p>\n Now let\u2019s take a look at how to use this new feature.<\/p>\n All of the supported APIs follow a similar format. After you\u2019ve uploaded your asset, you then create a job with any required and optional arguments. Consider the Create PDF operation<\/a>. When making the REST call, the body can be as simple as this:<\/p>\n To specify a webhook, you add a new property to your request body, For now, don\u2019t worry about This means:<\/p>\n Here\u2019s an example of a function that takes an asset and webhook (along with credential information) and kicks off a Create PDF job:<\/p>\n I\u2019ll share complete examples of my demos at the end of this article.<\/p>\n Now that you\u2019ve seen how to specify a webhook when creating jobs, how do you actually work with them?<\/p>\n That\u2019s something I can\u2019t really answer here as it\u2019s going to depend on your own architecture and setup. To be clear, you need something<\/em>, whether it\u2019s a web server or a serverless endpoint, that can respond to the webhook call.<\/p>\n There\u2019s a near infinite list of ways that you can do that, but for today, I\u2019ll share an incredibly simple Node.js script that when run, and exposed publicly, will listen and report on requests. My thanks go to Todd Sharp<\/a> for helping me with this.<\/p>\n Here\u2019s the entire server:<\/p>\n When run from the command line, it will listen on port 3000 and on every request, dump out to the console and body and headers. Finally, it always returns this JSON body:<\/p>\n This is required<\/strong> for your webhook so however you build it, ensure you return this response!<\/p>\n As mentioned in the comments, one way this script could be exposed publicly is via ngrok, so after running that, you can take the resulting URL and use that as your webhook.<\/p>\n Once used in a job, the webhook will be called when the job is done, and you can see an example request body below:<\/p>\n Now, looking at this, you may wonder \u2014 how do I associate the data in this request to my original job? You can see the In my last test, it looked like so:<\/p>\n https:\/\/pdf-services-ue1.adobe.io\/operation\/createpdf\/FAQjIUIGfuIkgcBMMunRsZ56P6qoQ4bR\/status<\/a><\/p>\n You can see the Another option is the use of custom headers. Remember back when I showed you the \u2018shape\u2019 of a request that includes webhooks, it looked like so:<\/p>\n The When Acrobat Services completes work on your job and hits your webhook, it will pass those values as custom HTTP headers. You can then check for them in your code.<\/p>\n Here\u2019s a modified version of the function shown earlier that includes a header based on the current date. This probably wouldn\u2019t be useful, but gives you an idea how it looks.<\/p>\n If you remember, or server code dumps out headers too. When using the version above, here\u2019s what you can see when the webhook is executed.<\/p>\n You can see the custom To get started testing this new feature out, sign up for your free credentials<\/a> today and hit up our support forums<\/a> if you\u2019ve got any questions. You can find the complete source code for the demos in this post here: https:\/\/github.com\/cfjedimaster\/document-services-demos\/tree\/main\/webhooks<\/a><\/p>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n<\/div>\n![\"\"](\"https:\/\/miro.medium.com\/v2\/resize:fit:640\/format:webp\/1*JqAR0xExNOvXZCveEMb_yw.png)
notifiers<\/code>. notifiers<\/code> is an array of objects that take this shape:<\/p>\nheaders<\/code> or type<\/code> (type<\/code> will always be ‘CALLBACK’), but note the url<\/code> property. This is the URL that you’re asking Acrobat Services to request when the process is done. At minimum, a Create PDF body with a webhook would look like so:<\/p>\njobID<\/code> value there and it will match a portion of the URL returned from the job creation. If you remember, the job is created by the API call and returned in the Location<\/code> header.<\/p>\njobID<\/code> in the data sent to the webhook matches the string before status<\/code> in the URL above. A bit of string parsing would make it possible to connect the two, but you must handle this yourself<\/em>. Since it’s asynchronous, you’ll need to store the job ID in a database or other persistence system.<\/p>\nheaders<\/code> value is optional and can be any number of name and values. So for example:<\/p>\ncats<\/code> header along with the usual headers sent in a request. Again, the validation, connection, etc. between the initial request and the webhook call is up to you, but you’ve got options for how you handle that. (As a quick aside, note you can also write webhooks using PowerAutomate. I’ll have a demo of this in the future.)<\/p>\n