Introducing Webhook Support in Acrobat Services | by Raymond Camden | Jan, 2024
Our new webhook support provides another powerful way to interact with our services.
This week the Acrobat Services team launched new support for webhooks with our APIs.
In this post, I’ll demonstrate how they work and what they provide to developers. Before getting into the details, some notes.
First off, this new feature is only available to folks using the Java SDK (updated this week to version 4) or the REST API directly. I’m a Node.js developer and prefer the REST API over the SDK anyway, so the examples provided here will be Node.js-based.
Secondly, this feature only works with “internal” files, or assets you upload to Adobe for processing. It isn’t yet supported with cloud storage providers.
Lastly, while this new feature is supported in all the various APIs within Acrobat Services, currently PDF Properties is not supported. It will be at a later time.
At a basic level, a webhook is a way for a service to let your code know something has happened. To be clear, it’s to let your code, not you specifically, know something that has happened.
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.
In some ways, it’s 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.
Webhooks can be especially useful for cases where operations take “some time”. I put that in quotes to cover the widest range of possible versions of that. Most Acrobat Services operate in seconds, but as it’s not instantaneous, it does take “some time.” You can imagine other APIs, perhaps involving video production, where “some time” could instead be minutes of time, or even hours.
With situations like this, a webhook is useful as it lets my code start the “slow” process and the webhook can let me know when things are done. That’s exactly how the webhook feature of Acrobat Services will help developers!
Now let’s take a look at how to use this new feature.
All of the supported APIs follow a similar format. After you’ve uploaded your asset, you then create a job with any required and optional arguments. Consider the Create PDF operation. When making the REST call, the body can be as simple as this:
To specify a webhook, you add a new property to your request body, notifiers. notifiers is an array of objects that take this shape:
For now, don’t worry about headers or type (type will always be ‘CALLBACK’), but note the url 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:
This means:
Here’s an example of a function that takes an asset and webhook (along with credential information) and kicks off a Create PDF job:
I’ll share complete examples of my demos at the end of this article.
Now that you’ve seen how to specify a webhook when creating jobs, how do you actually work with them?
That’s something I can’t really answer here as it’s going to depend on your own architecture and setup. To be clear, you need something, whether it’s a web server or a serverless endpoint, that can respond to the webhook call.
There’s a near infinite list of ways that you can do that, but for today, I’ll 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 for helping me with this.
Here’s the entire server:
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:
This is required for your webhook so however you build it, ensure you return this response!
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.
Once used in a job, the webhook will be called when the job is done, and you can see an example request body below:
Now, looking at this, you may wonder — how do I associate the data in this request to my original job? You can see the jobID 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 header.
In my last test, it looked like so:
https://pdf-services-ue1.adobe.io/operation/createpdf/FAQjIUIGfuIkgcBMMunRsZ56P6qoQ4bR/status
You can see the jobID in the data sent to the webhook matches the string before status in the URL above. A bit of string parsing would make it possible to connect the two, but you must handle this yourself. Since it’s asynchronous, you’ll need to store the job ID in a database or other persistence system.
Another option is the use of custom headers. Remember back when I showed you the ‘shape’ of a request that includes webhooks, it looked like so:
The headers value is optional and can be any number of name and values. So for example:
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.
Here’s a modified version of the function shown earlier that includes a header based on the current date. This probably wouldn’t be useful, but gives you an idea how it looks.
If you remember, or server code dumps out headers too. When using the version above, here’s what you can see when the webhook is executed.
You can see the custom cats 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.)
To get started testing this new feature out, sign up for your free credentials today and hit up our support forums if you’ve 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
