Customizable Webhooks: Integration Without the Effort

Test

We are very excited about our new Customizable webhooks features and we’re confident that our webhooks are among the most powerful and easy to use of any app.

Customizable webhooks enable direct communication between Amplience Dynamic Content and external APIs such as Algolia search, Slack and Jira. They significantly reduce the development effort and in many cases remove the need for a developer to build an additional integration service.

You lost me at webhooks

Webhooks are a way for one software service to automatically send messages or data to another. When you receive an email about a PayPal purchase or an SMS confirming that your DHL package has been shipped, the chances are that a webhook is responsible.

There is an excellent article on Zapier's blog for those of you who want to know more.

How do customizable webhooks work?

Many apps and services have webhook settings hidden away under custom settings or APIs. A standard webhook will have a user configurable URL to which it will send data, in a format defined by the system sending the data.

The webhook will be sent when a defined event or action occurs in the sending app.

To receive a webhook, a system will have to accept the request and understand the data in the format in which it has been sent, before processing it and triggering any further actions.

Dynamic Content's customizable webhooks simplify this process by providing the following features:

1. Custom payloads: allows developers to transform the webhook’s request body into any format using handlebars templating. Importantly, it is possible to send data from the full content graph, including linked content.

2. Custom headers: sending additional headers with the request enables basic authorization, opening up 1000s of apis. Custom headers could also be used to override the content type, for example to send xml

3. Filters: filtering allows developers fine-grained control over when a webhook will be triggered. For example only index a specific content type in algolia search or only send content items with a specific workflow status to a translation service.

4. Configurable request methods: You can create a webhook using PUT, PATCH or DELETE as well as POST. This allows you to perform more operations in external apps, such as updating an existing record in a search index or deleting a resource when an event occurs in Dynamic Content.

5. Templated webhook URLs: When sending a PUT, PATCH or DELETE request to an API, you will generally have to identify the object which you want to update or delete. To assist with this, you can now add code to your request URL to generate a predictable value such as an ID or label. Our library of handlebars helpers even allows you to URL encode the value.

6. Awesome testing and debugging features: Our new webhooks testing tool speeds up development by allowing you to process all of your webhook settings and see the generated output without triggering a new request. Previous requests can also be resent to assist in development of external integration services.

What are common uses for customizable webhooks?

When will customizable webhooks do the job?

As I mentioned in the introduction, for many use cases customizable webhooks will remove the need for an API orchestration layer (or integration service) for server-to-server integrations. Data transformation via custom payloads ensures interoperability between systems, custom headers enable authorization / mediation, and filters provide fine grain control over your workflow. If the following conditions are met, a webhook alone will suffice:

• Create, update or delete a record via a single API request, triggered by a single event in Dynamic Content

• Simple authorization via header(s)

• Transforming data into a specific JSON, XML or other format.

When do I need to build an additional service?

If you have any of the following requirements you may need to build an integration service, though you can still use our customizable webhooks features to keep your service simple.

• Logic based on the API response

• Multiple, sequential requests from a single action

• Complex auth patterns

• Requirement for very large request bodies

Detailed examples

I want to message a Slack channel when an edition is scheduled or published

• Trigger on Edition - Scheduled and Edition - Published

• Create a custom payload in the format required by Slack including the edition name, start date and end date:

• For detailed instructions, see our Slack integration guide

1{ 
2"blocks": [
3{
4    "type": "section",
5    "text": {
6        "type": "mrkdwn",
7        "text": "{{#eq dynamic-content.edition.scheduled }}Edition scheduled: {{else}}Edition published: {{/eq}}{{payload.name}}"
8    }
9},
10{
11    "type": "context",
12    "elements": [
13        {
14            "type": "mrkdwn",
15            "text": "Start: {{payload.start}}"
16        }
17    ]
18}
19{{#if payload.activeEndDate}}
20,
21{
22    "type": "context",
23    "elements": [
24        {
25            "type": "mrkdwn",
26            "text": "End: {{payload.end}}"
27        }
28    ]
29}
30{{/if}}
31
32]
33}

I want to receive an SMS when a content item is assigned to me

• Set up a Twilio account or use your existing details

• Add your webhook URL as follows: 

  1https://api.twilio.com/2010-04-01/Accounts/<twilio_account_sid>/Messages.json

  Replace <twilio_account_sid> with your Twilio account SID

• Trigger on Content item - Assignee change

• Filter on

  • JSONPath: 

    1$.payload.assignees[?(@ == '<dc-user-id>')]

  • Value: 

    1<dc-user-id>

  Replace <dc-user-id> with the Dynamic Content user id for the user you want to message. To find this you can assign a content item to the user, then look at the webhook activity log or use our webhook testing tool to find the value in the assignees array of the standard payload.

• Add a basic auth header with Username: <twilio_account_sid> and Password: <twilio_auth_token>

• Add a content-type header to override our standard content-type header with the value 

  1application/x-www-form-urlencoded

  . This format is required by the Twilio API.

• Create a custom payload including the label of the content item assigned to you, the phone number from your Twilio dashboard and the phone number where you will receive test SMS messages

1From=+<your_twilio_number>&To=+<your_verified_number>&Body=Content%20Item%20Assigned to you%20{{encodeURI payload.label}}

I want to send a content item to my translations agency when the workflow status is 'Ready for translation'

• Trigger on Content item - Status change

• Filter on

  • JSONPath: 

    1$.payload.workflowStatusLabel

  • Value: 

    1Ready for translation

• Create a custom payload in the format required by your translations agency

I want to index published content items in an Algolia search index

• Trigger on Snapshot - Published

• Filter on

  • JSONPath: 

    1$.payload.rootContentItem.contentTypeUri

  • Value: 

    1<my-schema-id>

• For detailed instructions, see part 1 of our Algolia Search integration guide

Where to go from here

We've covered just some of the ways that you can use customizable webhooks to power your integrations with Dynamic Content. The best way to find out what our webhooks can do is to build your own, so take a look at the examples on our documentation site and start integrating.