Features

TypeScript Webhooks

During building a public platform, you will run into situations where you need to listen to events from external services to automatically trigger your implementation. One common approach are webhooks. Webhooks are regular HTTP endpoints that are called by external services. There is no standard how webhooks are triggered or implemented. We provide the most flexible solution for you. You can implement webhooks in TypeScript using any Node.js package. Webhooks are also deeply integrated in the developer workflow. If you change a file in wunderctl up mode, we will hot-reload your webhooks.

For example, you might want to receive message when a User has starred your repository on Github to send him a thank you email with the next steps. With WunderGraph it is very easy to add secure webhooks to your WunderNode. You only need to create a webhook function in .wundergraph/webhooks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// .wundergraph/webhooks/github.ts
import type {
Webhook,
WebhookHttpEvent,
WebhookHttpResponse,
} from '@wundergraph/sdk'
import type { InternalClient } from '../generated/wundergraph.internal.client'
const webhook: Webhook<
InternalClient,
WebhookHttpEvent<
{ myBodyVar: string },
{ myQueryVar: string },
{ myHeaderVar: string }
>,
WebhookHttpResponse<
{ myResponseBodyVar: string },
{ myResponseHeaderVar: string }
>
> = {
handler: async (event, context) => {
return {
statusCode: 200,
headers: {
myResponseHeaderVar: 'myResponseHeaderValue',
},
body: {
hello: 'github',
},
}
},
}
export default webhook

After adding your first webhook, you can test it by calling http://127.0.0.1:9991/app/main/webhooks/github. It should return { hello: 'github' }.

Access the original client request

You have access to the original client request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// .wundergraph/webhooks/github.ts
import type { Webhook } from '@wundergraph/sdk'
import type { InternalClient } from '../generated/wundergraph.internal.client'
const webhook: Webhook<InternalClient> = {
handler: async (event, context) => {
event.body
event.url
event.headers
event.method
event.query
return {
statusCode: 200,
headers: {
'Content-Type': 'application/json',
},
body: {
hello: 'github',
},
}
},
}
export default webhook

Call internal operations

You can call internal operations from webhooks. Ensure to import the generated client to get a type-safe api.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// .wundergraph/webhooks/github.ts
import type { Webhook } from '@wundergraph/sdk'
import type { InternalClient } from '../generated/wundergraph.internal.client'
const webhook: Webhook<InternalClient> = {
handler: async (event, context) => {
const data = context.internalClient.queries.Dragons()
console.log(data)
return {
statusCode: 200,
body: {
hello: 'github',
},
}
},
}
export default webhook

Configure a verifier for your webhook

Implementing a webhook is more than just adding a HTTP handler to your application. In order to securely integrate Github, we have to ensure that only Github is able to call your endpoint. We can solve that by using webhook verifiers. Almost every platform has different requirements.

GitHub verifier

For Github, you can use our verifier in the SDK that implements the validation of the signature without writing any code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// .wundergraph/wundergraph.server.ts
import {
configureWunderGraphServer,
EnvironmentVariable,
GithubWebhookVerifier,
} from '@wundergraph/sdk'
import type { HooksConfig } from './generated/wundergraph.hooks'
import type { WebhooksConfig } from './generated/wundergraph.webhooks'
import type { InternalClient } from './generated/wundergraph.internal.client'
export default configureWunderGraphServer<
HooksConfig,
InternalClient,
WebhooksConfig
>(() => ({
webhooks: {
// Enable this if you configure this endpoint on Github.
// Don't forget to set the environment variable before starting your WunderNode
github: {
verifier: GithubWebhookVerifier(new EnvironmentVariable('GITHUB_SECRET')),
},
},
}))

Generic HMAC Verifier

The HMAC validation protocol is also used by other platforms.
You can use our generic HMAC verifier to validate other webhooks as well.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// .wundergraph/wundergraph.server.ts
import {
configureWunderGraphServer,
EnvironmentVariable,
GithubWebhookVerifier,
} from '@wundergraph/sdk'
import type { HooksConfig } from './generated/wundergraph.hooks'
import type { WebhooksConfig } from './generated/wundergraph.webhooks'
import type { InternalClient } from './generated/wundergraph.internal.client'
export default configureWunderGraphServer<
HooksConfig,
InternalClient,
WebhooksConfig
>(() => ({
webhooks: {
github: {
verifier: CreateWebhookVerifier({
kind: WebhookVerifierKind.HMAC_SHA256,
signatureHeaderPrefix: 'sha256=',
secret: new EnvironmentVariable('YOUR_SECRET'),
signatureHeader: 'X-Hub-Signature',
}),
},
},
}))

How to

If you're looking for more specific information on how to configure Webhooks, have a look at the wundergraph.server.ts reference.

Was this article helpful to you?
Provide feedback

Edit this page